Creating High-Quality Claude Skills Skill

Creating High-Quality Claude Skills

Use this skill when creating or improving Claude skills to ensure they follow official best practices and work effectively across all Claude models.

Core Principles

Conciseness: Skills share the context window. Only include information Claude doesn't already have.

Appropriate Freedom: Match instruction detail to task needs:

High freedom: Multiple valid approaches (use text instructions)
Medium freedom: Preferred patterns with flexibility (use pseudocode/guidance)
Low freedom: Exact sequences required (use specific bash/python scripts)

Progressive Disclosure: Keep SKILL.md under 500 lines. Split content into reference files when approaching this limit. All references must be one level deep.

Phase 1: Initial Clarification

BEFORE planning or writing the skill, use the AskUserQuestion tool to gather structured feedback on skill requirements — but only for questions the conversation hasn't already answered.

Instruction detail level: How much freedom should Claude have? (single select)
- High freedom — multiple valid approaches, text instructions only
- Medium freedom — preferred patterns with flexibility, pseudocode/guidance
- Low freedom — exact sequences required, specific scripts
Success criteria: How will success be measured? Suggest options contextually based on skill type. (multiSelect)
Invocation: Who triggers this skill? (single select)
- Claude, proactively when conditions match (default)
- Only the user, via slash command (disable-model-invocation: true)
- Only Claude, never shown in the menu (user-invocable: false)
Save location: where does the skill live? (single select; skip if the caller already specified it — e.g. codifying-tasks passes this in)
- This project only → .claude/skills/<name>/
- All my projects → ~/.claude/skills/<name>/

Add 1–2 contextual questions only if essential to clarify workflow steps, inputs/outputs, or materials to include.

Phase 2: Design & Planning

Choose skill name
- [ ] Use gerund form (verb + -ing, max 64 chars)
- [ ] Lowercase letters, numbers, hyphens only
- [ ] Avoid: helper, utils, or words containing "anthropic"/"claude" — reserved
Write description
- [ ] State what the skill does AND when to use it (trigger phrases)
- [ ] Include specific keywords for discovery
- [ ] Keep under 1024 chars, write in third person
- [ ] Think: "How will this be found among 100+ skills?"
Plan content structure
- [ ] Single file (< 400 lines) or progressive disclosure
- [ ] Identify sections: workflow, examples, templates, validation
- [ ] Note which parts need high/medium/low freedom
Architecture diagram (optional) — for a multi-file skill with reference docs, templates, or branching flows, an ASCII diagram per reference/architecture-diagrams.md helps validate structure. Skip it for a simple single-file skill; don't spend tokens diagramming something trivial.
Present plan to user
- Proposed name, description, structure outline (and the diagram if you drew one)
- Adjust based on feedback before writing

Phase 3: Create Content

Write into the save location chosen in Phase 1 (<location>/skills/<name>/SKILL.md).

Write SKILL.md — valid frontmatter, only non-obvious information, checklists for complex workflows
Add supporting files if needed — templates/, reference/, scripts/, one level deep, SKILL.md stays under 500 lines
Implement feedback mechanisms identified in Phase 1 — validation checkpoints, quality loops, error handling

A brand-new skill may not load until the session restarts (or /reload-plugins for a plugin skill); tell the user rather than treating a not-yet-listed skill as broken.

Frontmatter Reference

Required shape (only description is strictly recommended; name defaults to the directory name):

---
name: skill-name-here
description: What this does and when to use it, with trigger keywords.
---

Optional fields worth knowing (current as of mid-2026):

| Field | Use for | |---|---| | argument-hint | Autocomplete hint, e.g. [filename] [format] | | arguments | Named positional args for $name substitution ($ARGUMENTS = all) | | disable-model-invocation: true | User-only skills (side effects, cost) | | user-invocable: false | Claude-only skills (hidden from / menu) | | allowed-tools / disallowed-tools | Pre-grant or remove tools while the skill runs | | model, effort | Override model or effort for this skill | | context: fork + agent: | Run the skill in a forked subagent instead of the main loop | | paths | Glob patterns; skill activates only when working with matching files | | when_to_use | Extra trigger phrases appended to description (combined cap 1536 chars) |

Skills installed via a plugin are invoked namespaced: /plugin-name:skill-name. Design names that read well after the colon.

Content Organization

Single SKILL.md when: under 400 lines, tightly related, needed all at once.

Progressive disclosure when: approaching 500 lines, distinct topics, conditional/advanced detail:

SKILL.md (overview + core workflow)
├── templates/        # files the skill fills in or copies
└── reference/        # detail loaded only when needed (one level deep, never nested)

Content Principles

Challenge every detail — is it essential, non-inferable, non-duplicative?

Only unique information — what Claude doesn't know, or what's specific to this use case:

## Data Processing Requirements

Use pandas with these constraints:
- Preserve original column order (df.reindex())
- Handle timestamps in Pacific timezone
- Round currency values to 2 decimal places

Workflows with checklists for complex tasks:

1. **Analyze Input**
   - [ ] Validate format
   - [ ] Check required fields
2. **Process Data**
   - [ ] Apply transformations
   - [ ] Validate output

Feedback loops where quality matters:

1. Run validation
2. If errors found → review → fix → return to step 1
3. If passes → proceed

Scripts and Code Guidelines

Error handling: scripts give specific, actionable messages (what failed, which rows, how to fix)
File paths: forward slashes only — data/input/file.csv
Dependencies: documented, with configuration values explained (no magic numbers)
MCP tools: fully qualified names (ServerName:tool_name)

See reference/scripts-and-code.md for comprehensive guidance.

Phase 4: Quality Checklist

Structure:

[ ] Valid YAML frontmatter; name follows conventions (gerund, ≤64 chars, lowercase/hyphens)
[ ] Description includes usage triggers (≤1024 chars, third person)
[ ] SKILL.md under 500 lines; supporting files one level deep
[ ] Frontmatter options match invocation intent (Phase 1, question 3)

Content:

[ ] Only information Claude doesn't already have
[ ] Consistent terminology; concrete examples; checklists on complex workflows
[ ] No time-sensitive information

Technical:

[ ] Scripts have explicit error handling
[ ] File paths use forward slashes
[ ] Dependencies documented

Phase 5: Verify the Skill Triggers Correctly

A skill that never fires (or fires on the wrong prompts) is a silent failure. Before calling it done, sanity-check the description against realistic prompts:

Should-trigger: name 2–3 prompts a user would actually type for this task. Does the description's wording and keywords make Claude reach for the skill? If a plausible request wouldn't surface it, the description is too narrow or missing keywords.
Should-NOT-trigger: name 1–2 adjacent prompts this skill should ignore (e.g. a generic question, a neighboring skill's job). Does the description risk over-firing or shadowing another skill? Tighten the scope if so.

For a non-trivial skill, run one real invocation (or, in a forked subagent, dry-run the workflow against a realistic input) and fix what breaks via the correcting-mistakes skill before shipping. Deploying an unexercised skill is deploying untested instructions.

Reference Files

Scripts and Code — error handling, dependencies, configuration
Architecture Diagrams — skill architecture diagram guidelines

Agent Skills: Creating High-Quality Claude Skills

Install this agent skill to your local

Skill Files