Guide for creating, auditing, and packaging Claude Code skills. This skill should be used when building new skills, improving existing skills, understanding skill structure, or packaging skills for distribution.
/plugin marketplace add kylesnowschwartz/SimpleClaude/plugin install sc-skills@simpleclaudeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/api-security.mdreferences/authoring-principles.mdreferences/common-patterns.mdreferences/skill-structure.mdreferences/use-xml-tags.mdreferences/using-scripts.mdreferences/using-templates.mdreferences/workflows-and-validation.mdscripts/init_skill.pyscripts/package_skill.pyscripts/quick_validate.pytemplates/router-skill.mdtemplates/simple-skill.mdworkflows/add-reference.mdworkflows/add-workflow.mdworkflows/audit-skill.mdworkflows/create-domain-expertise-skill.mdworkflows/create-new-skill.mdworkflows/get-guidance.mdworkflows/upgrade-to-router.md<essential_principles>
Skills are modular, filesystem-based capabilities that provide domain expertise on demand.
All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
skill-name/
├── SKILL.md # Router + principles
├── workflows/ # Step-by-step procedures (FOLLOW)
├── references/ # Domain knowledge (READ)
├── templates/ # Output structures (COPY + FILL)
└── scripts/ # Executable code (RUN)
No markdown headings in skill body. Use semantic XML tags (<objective>, <quick_start>, <success_criteria>).
SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed. </essential_principles>
<quick_start>
Initialize a new skill:
python scripts/init_skill.py my-skill-name --path /path/to/skills/
Validate a skill:
python scripts/quick_validate.py /path/to/skill-name/
Package for distribution:
python scripts/package_skill.py /path/to/skill-name/
</quick_start>
<intake> What would you like to do?Wait for response before proceeding. </intake>
<routing> | Response | Next Action | Workflow | |----------|-------------|----------| | 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to create workflow | | 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to audit/verify workflow | | 3, "add", "component" | Ask: "Add what? (workflow/reference)" | workflows/add-{type}.md | | 4, "guidance", "help" | General guidance | workflows/get-guidance.md | | 5, "package", "distribute" | Run packaging script | See quick_start |Progressive disclosure for option 1 (create):
Intent-based routing:
After reading the workflow, follow it exactly. </routing>
<quick_reference>
Simple skill (single file):
---
name: skill-name
description: What it does and when to use it.
---
<objective>What this skill does</objective>
<quick_start>Immediate actionable guidance</quick_start>
<success_criteria>How to know it worked</success_criteria>
Complex skill (router pattern):
SKILL.md:
<essential_principles> - Always applies
<intake> - Question to ask
<routing> - Maps answers to workflows
workflows/:
<required_reading> - Which refs to load
<process> - Steps
<success_criteria> - Done when...
references/:
Domain knowledge, patterns, examples
scripts/:
Executable code Claude runs as-is
</quick_reference>
<reference_index>
All in references/:
Structure: skill-structure.md Principles: authoring-principles.md XML Tags: use-xml-tags.md Patterns: common-patterns.md Scripts: using-scripts.md Templates: using-templates.md Validation: workflows-and-validation.md Security: api-security.md </reference_index>
<workflows_index>
All in workflows/:
| Workflow | Purpose |
|---|---|
| create-new-skill.md | Build a skill from scratch |
| create-domain-expertise-skill.md | Build exhaustive domain knowledge base |
| audit-skill.md | Analyze skill against best practices |
| verify-skill.md | Check if content is still accurate |
| add-workflow.md | Add a workflow to existing skill |
| add-reference.md | Add a reference to existing skill |
| upgrade-to-router.md | Convert simple skill to router pattern |
| get-guidance.md | Help decide what kind of skill to build |
| </workflows_index> |
<yaml_requirements>
Required fields:
---
name: skill-name # lowercase-with-hyphens, matches directory
description: ... # What it does AND when to use it (third person)
---
Name conventions: create-*, manage-*, setup-*, generate-*, build-*
</yaml_requirements>
<success_criteria> A well-structured skill:
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.