Skill Creation Guide
Scope
Use this skill when:
- Creating new Agent Skills
- Understanding SKILL.md format and conventions
- Learning best practices for skill authoring
Skill Structure
skill-name/
├── SKILL.md # Required: Instructions and metadata
├── scripts/ # Optional: Helper scripts
├── templates/ # Optional: Document templates
└── resources/ # Optional: Reference filesSKILL.md Format
Required Frontmatter
---
name: my-skill-name
description: A clear description of what this skill does and when to use it.
---Body Structure
# Skill Name
Detailed description of the skill's purpose.
## When to Use This Skill
- Use case 1
- Use case 2
## Instructions
[Detailed instructions for the agent]
## Examples
[Real-world examples]Best Practices
- Keep descriptions exhaustive: The frontmatter description helps agents decide when to trigger the skill.
- Focus on execution: The body should contain clear, actionable steps.
- Use progressive disclosure: Put detailed references in
references/folder. - Include scripts for automation: Use helper scripts for deterministic operations.
- Keep SKILL.md under 500 lines: For optimal performance.
- Test across platforms: Verify skills work with Claude Code, Codex, etc.
Token Efficiency
Skills employ progressive disclosure architecture:
- Metadata loading (~100 tokens): Agent scans available skills
- Full instructions (<5k tokens): Load when skill is activated
- Bundled resources: Only load as needed
Platform-Specific Paths
| Platform | Project Path | Global Path |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Codex | .codex/skills/ | ~/.codex/skills/ |
| Cursor | .cursor/skills/ | ~/.cursor/skills/ |
| Gemini CLI | .gemini/skills/ | ~/.gemini/skills/ |
| GitHub Copilot | .github/skills/ | ~/.copilot/skills/ |
Quality Checklist
- Clear, actionable instructions
- Includes real-world examples
- Written for AI agents, not end users
- Documents prerequisites and dependencies
- Includes error handling guidance
- Tested on target platform(s)
Full Resource List
For more detailed skill creation resources, complete link lists, or the latest information, use WebFetch to retrieve the full README.md:
https://raw.githubusercontent.com/gmh5225/awesome-skills/refs/heads/main/README.mdThe README.md contains the complete categorized resource list with all links.