Skill Creator
Create effective, portable skills that work across Claude.ai, Claude Code, and the API. A skill is a folderized instruction set that encodes a reusable workflow once, then applies it consistently.
Skill Structure
skill-name/
├── SKILL.md # Required: YAML frontmatter + markdown instructions
├── scripts/ # Optional: executable code for deterministic tasks
├── references/ # Optional: docs loaded into context as needed
└── assets/ # Optional: files used in output (templates, images, fonts)SKILL.md
Two parts:
- Frontmatter (YAML) —
nameanddescriptionfields. Always in context. Determines when the skill triggers. - Body (Markdown) — Instructions, workflows, and pointers to bundled resources. Loaded only after triggering.
Bundled Resources
| Directory | Purpose | Loaded into context? |
|---|---|---|
scripts/ | Executable code (Python/Bash) for deterministic operations | Only when Claude reads them |
references/ | Documentation Claude consults while working | On demand |
assets/ | Files used in output (templates, images, fonts) | Never — used directly in output |
Do not include README.md, CHANGELOG.md, or any auxiliary documentation files.
Core Principles
Context Budget
The context window is shared. Only include what Claude does not already know. Prefer concise examples over verbose explanations. Every paragraph must justify its token cost — remove paragraphs that do not.
Hard limit: Keep SKILL.md body under 5,000 words. Move detailed content to references/.
Degrees of Freedom
Match specificity to the task's fragility:
- High freedom (text guidance) — multiple valid approaches, context-dependent
- Medium freedom (pseudocode/parameterized scripts) — preferred pattern, some variation ok
- Low freedom (exact scripts) — fragile operations, consistency critical
Progressive Disclosure
Three-layer loading minimizes context usage:
- Frontmatter (under 100 words) — always in context
- SKILL.md body (under 5,000 words) — loaded when skill triggers
- Bundled resources (unlimited) — loaded as needed
Keep SKILL.md lean. Split into reference files when exceeding 300 lines. Always reference split files from SKILL.md with clear descriptions of when to read them.
Composability and Portability
- Skills must coexist without conflicting instructions
- Skills must work across Claude.ai, Claude Code, and the API
- Do not hard-depend on environment-specific tooling
Workflow
1. Understand
Gather concrete use cases before building anything.
Entry: User request to create or improve a skill.
Actions:
- Identify 2-3 concrete examples of how the skill will be used
- For each example: what triggers it, what steps run, what the end result looks like
- Ask targeted questions — avoid overwhelming the user with too many at once
Exit: Clear understanding of the skill's scope, triggers, and expected outputs.
2. Plan
Determine what reusable resources the skill needs.
Entry: Concrete use cases from Step 1.
Actions:
- For each use case: what gets rewritten every time? That belongs in the skill.
- Categorize resources:
- Code rewritten repeatedly → scripts/ - Knowledge referenced repeatedly → references/ - Templates/assets used in output → assets/
- Decide SKILL.md structure — see
references/workflows.mdfor common patterns.
Exit: List of resources to create and SKILL.md outline.
3. Build
Create the skill folder and write its contents.
Entry: Resource list and SKILL.md outline from Step 2.
Actions:
- Create the skill folder following the structure above. If
scripts/init_skill.pyis available in the environment, use it as a scaffolding accelerator:scripts/init_skill.py <skill-name> --path <output-directory>Otherwise, create the folder and SKILL.md manually. - Write bundled resources first — scripts, references, assets. Test scripts by running them. Delete any scaffolding files not needed.
- Write SKILL.md:
- Frontmatter: Follow references/description-authoring.md for the description formula - Body: Use imperative/infinitive form. Structure by workflow steps or task categories. - Keep the body lean — point to references for depth - Validate against references/validation-checklist.md to ensure the skill meets all structural requirements
- Delete unused scaffolding — remove example files and empty directories.
Exit: Complete skill folder with all resources and SKILL.md.
4. Test
Validate triggering and output quality.
Entry: Complete skill from Step 3.
Actions:
- Run triggering tests (positive and negative prompts)
- Run functional tests on real tasks
- Compare results against baseline (no skill)
See references/testing-iteration.md for detailed testing methodology and success criteria.
Exit: Skill triggers on 9 out of 10 relevant prompts and produces consistent output.
5. Iterate
Refine based on real usage.
Entry: Test results or user feedback.
Actions:
- Diagnose issues: undertriggering, overtriggering, or execution failures
- Apply targeted fixes per
references/testing-iteration.md - Re-test affected areas
Exit: Skill meets success criteria across real-world usage.
Packaging
Package a finished skill as a .skill file (zip with .skill extension). If scripts/package_skill.py is available, use it — it validates and packages automatically:
scripts/package_skill.py <path/to/skill-folder> [output-directory]Otherwise, zip the skill folder manually ensuring SKILL.md is at the root of the archive.
Reference Guides
Consult these based on the skill's needs:
- Description and triggers:
references/description-authoring.md— formula, trigger phrases, negative triggers, hard constraints - Workflow patterns:
references/workflows.md— sequential, multi-service, iterative, context-aware, domain intelligence - Output patterns:
references/output-patterns.md— templates and example-based output guidance - Testing and iteration:
references/testing-iteration.md— triggering tests, functional tests, performance metrics, diagnostics - Validation checklist:
references/validation-checklist.md— structural requirements every skill must meet - Troubleshooting:
references/troubleshooting.md— common failures and resolution paths
Examples
Positive Trigger
User: "Create a new skill for converting PDFs to markdown with reusable scripts."
Expected behavior: Follow this skill's workflow — understand use cases, plan resources, build the skill.
Non-Trigger
User: "Find and fix a TypeScript type error in src/api/client.ts."
Expected behavior: Do not use this skill. Choose a more relevant skill or proceed directly.
Troubleshooting
Created Skill Does Not Trigger
- Error: The skill is not selected when expected.
- Cause: Description lacks specific trigger phrases or is too vague.
- Solution: Rewrite description following
references/description-authoring.md.
Created Skill Is Too Verbose
- Error: SKILL.md exceeds 5,000 words or fills excessive context.
- Cause: Detailed content belongs in references, not the body.
- Solution: Move detailed content to
references/files. Keep SKILL.md as a lean workflow guide.
Output Is Inconsistent Across Sessions
- Error: Skill produces different quality results each time.
- Cause: Instructions are ambiguous or lack explicit validation steps.
- Solution: Add concrete examples, exact commands, and verification steps. See
references/troubleshooting.md.