This skill should be used when the user asks to "create a skill", "write SKILL.md", "what are skill best practices", "how to optimize a skill", "improve skill quality", or mentions skill development, trigger phrases, skill structure, or content quality. Provides comprehensive guidance for creating high-quality Claude Code skills following latest standards.
Provides comprehensive guidance for creating high-quality Claude Code skills following latest standards and best practices.
npx claudepluginhub within-7/minto-plugin-toolsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
SKILL_fixes.mdreferences/common-mistakes.mdreferences/content-quality.mdreferences/structure-guide.mdreferences/trigger-patterns.mdCreate effective Claude Code skills that provide specialized knowledge and workflows. High-quality skills transform Claude from a general-purpose assistant into a domain expert equipped with procedural knowledge.
Use a three-level loading system to manage context efficiently:
Keep SKILL.md lean. Move detailed content to references/ files.
The description field determines when Claude activates the skill. Use specific, concrete phrases:
✅ Good:
description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", or mentions hook events
(PreToolUse, PostToolUse, Stop).
❌ Bad:
description: Use this skill when working with hooks.
Always write descriptions in third person: "This skill should be used when..."
❌ Avoid second person: "Use this skill when you want to..."
Write skill body instructions using imperative/infinitive form (verb-first):
✅ Good:
Create the skill directory structure.
Validate the frontmatter syntax.
Check required fields.
❌ Bad:
You should create the directory structure.
You need to validate the syntax.
Every skill must have:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description required)
│ └── Markdown body
└── [Optional resources]
├── scripts/ - Executable utilities
├── references/ - Detailed documentation
└── assets/ - Templates and output files
Required fields:
name - Skill name (Title Case)description - Third-person description with specific triggersOptional fields:
version - Skill version (semantic versioning)Example:
---
name: My Skill
description: This skill should be used when the user asks to "task 1",
"task 2", or "task 3".
version: 0.1.0
---
Target 1,500-2,000 words maximum. Include:
Essential Content:
Keep focused: Move detailed patterns, advanced techniques, and comprehensive examples to references/ files.
Move to references/ when content is:
Benefits:
Never duplicate: Information should live in either SKILL.md OR references/, not both.
Store complete, runnable examples:
Users can copy and adapt these directly.
Include executable tools when:
Examples:
List exact phrases users would say:
✅ Good:
description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
or mentions hook events (PreToolUse, PostToolUse, Stop).
❌ Bad:
description: Load when user needs hook help.
Include different ways users might ask:
description: This skill should be used when the user asks to "create a skill",
"write a new skill", "add a skill to my plugin", "how do I create SKILL.md",
or mentions skill development, SKILL.md files, or skill best practices.
Mention relevant concepts and terminology:
description: This skill should be used when working with MCP servers,
mentions "add MCP integration", "configure stdio server", or discusses
Model Context Protocol, MCP tools, or server authentication.
Use imperative form throughout:
Never use second person:
Be objective and instructional:
Structure SKILL.md with:
Use markdown features:
Make content actionable:
Avoid ambiguity:
❌ Problem:
description: Provides guidance for skills.
Why: Vague, no specific triggers, not third person.
✅ Fix:
description: This skill should be used when the user asks to "create a skill",
"write SKILL.md", or mentions skill development, trigger phrases, or skill
structure.
❌ Problem:
✅ Fix:
references/❌ Problem:
You should start by creating the directory.
You need to configure the settings.
✅ Fix:
Start by creating the directory.
Configure the settings before use.
❌ Problem:
SKILL.md doesn't mention references/ files.
✅ Fix:
## Additional Resources
### Reference Files
- **`references/structure-guide.md`** - Detailed structure standards
- **`references/trigger-patterns.md`** - Trigger phrase patterns
### Examples
- **`examples/good-skill.md`** - Example SKILL.md
For simple knowledge without complex resources:
skill-name/
└── SKILL.md
Use when: Skill provides straightforward guidance, no utilities needed.
skill-name/
├── SKILL.md
├── references/
│ └── detailed-guide.md
└── examples/
└── working-example.md
Use when: Skill has detailed documentation or examples.
skill-name/
├── SKILL.md
├── references/
│ ├── patterns.md
│ └── advanced.md
├── examples/
│ ├── example1.md
│ └── example2.md
└── scripts/
└── validate.sh
Use when: Complex domain with utilities and comprehensive docs.
Before finalizing a skill, verify:
Structure:
name and descriptionDescription:
Content:
Resources:
Progressive Disclosure:
For comprehensive guidance on specific aspects:
references/structure-guide.md - Detailed structure and formatting standardsreferences/trigger-patterns.md - Trigger phrase optimization patternsreferences/content-quality.md - Content quality checklist and standardsreferences/common-mistakes.md - Common mistakes and how to fix themThese references provide in-depth coverage of each topic with examples and patterns.
Study these skills as best practice examples:
plugin-dev/skills/hook-development/ - Progressive disclosure, utilitiesplugin-dev/skills/agent-development/ - Strong triggers, referencesplugin-dev/skills/skill-development/ - Meta-example (this skill)Follow these steps when creating a skill:
Focus on strong trigger descriptions, progressive disclosure, and imperative writing to create effective skills that load when needed and provide targeted guidance.
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.