skills-scaffolding_skill

Overview

This skill guides creation and maintenance of Claude Code skills to extend Claude with specialized knowledge, workflows, and tool integrations. It explains required files, YAML frontmatter, resource organization, and progressive disclosure patterns to keep skills efficient and discoverable. Use this skill to structure new skills, improve existing ones, and decide between skills and slash commands.

How this skill works

Inspect required SKILL.md metadata and body to determine trigger conditions and core procedural guidance. Recommend and organize optional bundled resources (scripts/, references/, assets/) so Claude loads only what it needs. Provide concrete naming, YAML field, and content rules so Claude can reliably detect and apply the skill when relevant.

When to use it

• Creating a new Claude Code skill from scratch
• Updating or refactoring an existing skill to improve clarity or discoverability
• Writing YAML frontmatter (name and description) for a skill
• Organizing bundled resources: scripts, references, and assets
• Deciding whether functionality belongs in a skill or a slash command
• Applying progressive disclosure to optimize token usage

Best practices

• Begin SKILL.md with YAML frontmatter containing name and description in third-person form
• Keep SKILL.md concise; move large specs to references/ and include grep patterns for large files
• Organize scripts/ for deterministic tasks, references/ for documentation, and assets/ for files used in outputs
• Write instructions in imperative/infinitive form (verb-first) and include concrete examples and key rules
• Use kebab-case for directory names and title case for YAML skill name; keep lengths within specified limits
• Design SKILL.md so metadata triggers skill without loading all resources; load body or bundled files only when needed

Example use cases

• Create an ADO work-items skill with templates and naming conventions stored in SKILL.md and detailed field specs in references/
• Bundle a PDF rotation script in scripts/ so Claude can run or patch deterministic code instead of regenerating it each time
• Author brand-guidelines skill with assets/ containing logos and templates and references/ documenting color tokens and typography
• Refactor a long SKILL.md by moving large schemas to references/ and adding search patterns in the main file
• Decide to implement project-initialization steps as a slash command and ongoing guidance as a separate skill