Create Ultimate Skill

Create Ultimate Skill

Creation Workflow

When creating a new skill based on user's request: $ARGUMENTS

Phase 1: Define Use Cases

Ask the user:

1. Use cases: "Describe 2-3 specific scenarios where you'd want this skill to activate. What would you say to Claude, and what should it do?"
2. Non-use cases: "What should this skill NOT be used for?" (defines negative triggers)

Phase 2: Choose Archetype and Scope

Ask the user:

1. Archetype (see Archetypes section below)
2. Triggers: What phrases should activate this skill?
3. Scope: What's in scope vs out of scope?

Phase 3: Fetch Latest Documentation

Fetch the latest official skill documentation to verify current fields and constraints:

WebFetch: https://markdown.new/https://code.claude.com/docs/en/skills.md

Phase 4: Choose Save Location

Use AskUserQuestion:

• Personal (home folder): ~/.claude/skills/<skill-name>/ - available in all projects
• Project folder: .claude/skills/<skill-name>/ - project-specific
• Existing plugin: ask which plugin, then plugins/<plugin-name>/skills/

Phase 5: Create the Skill

Scaffold with init_skill.py or create manually:

python .claude/skills/create-ultimate-skill/scripts/init_skill.py <skill-name> --path <location>

Then write SKILL.md applying all rules below. Review with the checklist before presenting to user.

Phase 6: Summary

When complete, provide:

• Skill location and how to trigger it
• What it does
• Suggestions for improvement
• Testing prompts the user can try

Frontmatter Hard Rules

• description MUST be a single-line plain string. NEVER use YAML multi-line indicators (>-, |, >, |-). Multi-line descriptions break frontmatter parsing.
• allowed-tools MUST be a single-line comma-separated string (e.g. allowed-tools: Read, Write, Edit). NEVER use YAML list syntax.

Required Fields

Optional Fields

See references/api-reference.md for full field documentation.

Archetypes

See references/archetypes.md for templates.

Description Rules

• Third person always ("Processes files" not "I help you")
• Include WHAT it does AND WHEN to trigger
• Specific trigger phrases users would say
• Add negative triggers ("Do NOT use for...") to prevent over-triggering
• Max 1024 characters

Template:

description: [What it does]. Use when [triggers]. Do NOT use for [exclusions].

Examples:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

description: Process and transform CSV data files. Use when working with CSV imports, exports, or data cleaning. Do NOT use for Excel files (.xlsx) or database queries.

SKILL.md Body Rules

• Imperative voice ("Extract the data", "Run validation")
• Never second person ("You should...")
• Concise - challenge each line: "Does Claude need this?"
• Under 500 lines, under 5,000 words (~2,000 ideal)
• Put critical instructions at the top of the file
• Use scripts for validation where possible - code is deterministic, language interpretation is not
• "Take your time to do this thoroughly" is more effective in user prompts than in SKILL.md

Structure Rules

skill-name/
├── SKILL.md              # Core guidance only
├── references/           # Detailed docs (on-demand)
├── examples/             # Working code samples
└── scripts/              # Executable utilities

• References ONE level deep only - no chains
• Long files (>100 lines): include TOC
• Never include README.md in skill folder (SKILL.md IS the readme)
• Forward slashes only (no Windows paths)

Anti-Patterns

Testing

Define success criteria before building:

• Quantitative: Trigger rate >90% of relevant queries, correct tool sequence, task completes without user intervention
• Qualitative: Output matches expected format, no hallucinated commands, consistent across sessions

Debug technique: Ask Claude "When would you use the [skill name] skill?" - the response reveals how Claude interprets the description.

Test three areas:

1. Triggering: Direct trigger phrases, paraphrased requests, and edge cases that should NOT trigger
2. Functional: Run each use case end-to-end, check output format and accuracy
3. Performance: Compare skill-assisted vs manual - does the skill save time and improve quality?

Pro tip: Iterate on a single challenging task until Claude succeeds, then extract the winning approach into the skill. This grounds design in proven patterns rather than theory.

Iteration Signals

Utility Scripts

init_skill.py

python .claude/skills/create-ultimate-skill/scripts/init_skill.py <skill-name> --path <location>

Creates SKILL.md with template, plus scripts/, references/, assets/ directories.

package_skill.py

python .claude/skills/create-ultimate-skill/scripts/package_skill.py <path/to/skill> [output-dir]

Validates and creates distributable zip. Checks frontmatter, naming, ensures no TODOs remain.

Skill Review Mode

When reviewing an existing skill (triggered by --review or "review my skill"):

1. Read SKILL.md frontmatter, body, and supporting directories
2. Categorise issues by severity:
   • Critical: Won't trigger or wrong output (missing description, vague triggers, broken refs)
   • Major: Significantly reduces effectiveness (>5,000 words, no progressive disclosure)
   • Minor: Polish (inconsistent terminology, missing TOC, no negative triggers)
3. Generate structured review report:

## Skill Review: [skill-name]

### Summary
[Assessment, word counts, structure]

### Description Analysis
**Current:** [description]
**Issues:** [with severity]
**Suggested:** "[improved version]"

### Issues by Severity
#### Critical ([count])
- [File]: [Issue] - [Fix]
#### Major ([count])
- [File]: [Issue] - [Fix]
#### Minor ([count])
- [File]: [Issue] - [Suggestion]

### Rating: [Pass / Needs Improvement / Needs Major Revision]

### Priority Fixes
1. [Highest impact]
2. [Second]
3. [Third]

Review Checklist

• Use cases: 2-3 concrete scenarios defined
• name: lowercase, hyphens, ≤64 chars
• description: single-line plain string, third person, specific triggers, ≤1024 chars
• description: negative triggers if needed
• SKILL.md body: <500 lines, <5,000 words
• No README.md in skill folder
• References: one level deep
• Forward slashes only
• Examples concrete, not abstract

Latest Documentation

Before finalising any skill's frontmatter, fetch the latest official documentation to check for new fields, changed constraints, or updated rules:

WebFetch: https://markdown.new/https://code.claude.com/docs/en/skills.md

Further Reading

• Skill Archetypes
• Official API Reference