Skill Development
Create, structure, and improve Claude Code plugin skills with progressive disclosure and solid SKILL.md anatomy.
Overview
Skill Development is an agent skill most often used in Build (also Validate scope, Ship review) that teaches how to author effective Claude Code plugin skills with structure, metadata, and progressive disclosure.
Install
npx skills add https://github.com/anthropics/claude-code --skill skill-developmentWhat is this skill?
- Covers full skill anatomy: required SKILL.md frontmatter plus optional bundled resources
- Explains four skill value types: workflows, tool integrations, domain expertise, bundled assets
- Guidance on progressive disclosure and effective descriptions for plugin discovery
- Best practices when users ask to create, add, or organize skills in Claude Code plugins
- Positions skills as onboarding guides that turn general agents into specialists
- 4 enumerated skill benefit categories in SKILL.md
Adoption & trust: 13.1k installs on skills.sh; 131k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want reusable agent capabilities but your SKILL.md metadata, layout, or descriptions are too vague for Claude to load the right skill at the right time.
Who is it for?
Solo builders productizing repeated workflows as Claude Code skills or cleaning up an existing plugin skill library.
Skip if: One-off tasks with no reuse, or teams not using Claude Code’s skill/plugin packaging model.
When should I use this skill?
User wants to create a skill, add a skill to a plugin, write a new skill, improve skill description, organize skill content, or needs skill structure best practices.
What do I get? / Deliverables
You produce a well-formed skill package with clear frontmatter, disclosed steps, and optional bundled resources ready to ship inside a plugin.
- SKILL.md with valid YAML frontmatter
- Optional bundled scripts, references, or assets folder layout
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Agent-tooling is where solo builders package procedural knowledge into installable skills for their coding agents. Skill Development is explicitly about SKILL.md structure, descriptions, and bundled resources—not app feature code.
Where it fits
Decide which repeated planning steps belong in a skill versus inline prompts before building.
Scaffold a new SKILL.md with required metadata and optional reference folders for a payments integration.
Tighten skill descriptions so code-review and testing skills trigger on the right phrases.
Refactor an oversized skill into progressive disclosure sections after production pain points.
How it compares
Authoring guide for skill packages—not runtime MCP server setup or application feature development.
Common Questions / FAQ
Who is skill development for?
Claude Code plugin authors and indie builders who package domain workflows as installable skills with SKILL.md and bundled assets.
When should I use skill development?
During Build agent-tooling when creating skills, during Validate when scoping what to encode in a skill versus code, or during Ship review when improving descriptions so agents invoke skills reliably.
Is skill development safe to install?
It is documentation and structure guidance without mandated shell or network tools; review the Security Audits panel on this page for the plugin source you install from.
SKILL.md
READMESKILL.md - Skill Development
# Skill Development for Claude Code Plugins This skill provides guidance for creating effective skills for Claude Code plugins. ## About Skills Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess. ### What Skills Provide 1. Specialized workflows - Multi-step procedures for specific domains 2. Tool integrations - Instructions for working with specific file formats or APIs 3. Domain expertise - Company-specific knowledge, schemas, business logic 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter metadata (required) │ │ ├── name: (required) │ │ └── description: (required) │ └── Markdown instructions (required) └── Bundled Resources (optional) ├── scripts/ - Executable code (Python/Bash/etc.) ├── references/ - Documentation intended to be loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts, etc.) ``` #### SKILL.md (required) **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). #### Bundled Resources (optional) ##### Scripts (`scripts/`) Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks - **Benefits**: Token efficient, deterministic, may be executed without loading into context - **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments ##### References (`references/`) Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - **When to include**: For documentation that Claude should reference while working - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides - **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. ##### Assets (`assets/`) Files not intended to be loaded into context, but rather used within the output Claude produces. - **When to include**: When the skill needs files that will be used in the final output - **E