tools-only Ultimate Skill Creation Workflow
Create bleeding-edge Claude Code skills by combining three authoritative sources:
- Official plugin-dev toolkit (validation, AI-assisted creation)
- Community best practices (token hierarchy, archetypes, advanced patterns)
- Latest official documentation (current API fields)
Phase 1: Load Combined Knowledge
First, load the skill-mastery skill to have all best practices available:
Load the skill-mastery skill from this plugin using the Skill tool.
Phase 2: Understand Requirements
Based on the user's request: $ARGUMENTS
Ask clarifying questions to understand:
- Purpose: What problem does this skill solve?
- Archetype: Which pattern fits best?
- CLI Reference (tool documentation)
- Methodology (workflows, processes)
- Safety Tool (validation, guardrails)
- Orchestration (multi-agent coordination)
- Triggers: What phrases should activate this skill?
- Scope: What's in scope vs out of scope?
Phase 3: Fetch Latest Documentation
Use the claude-code-guide agent via Task tool to verify latest API fields:
Fetch the current official documentation for Claude Code skills frontmatter fields.
Confirm the current constraints for: name, description, allowed-tools, model, context, agent, hooks, user-invocable, disable-model-invocation.
Report any new fields or changed constraints.
Phase 4: Design Skill Architecture
Based on the archetype, design the structure:
CLI Reference Structure
skill-name/
├── SKILL.md (commands grouped by function)
└── references/
└── advanced-options.md
Methodology Structure
skill-name/
├── SKILL.md (philosophy + THE EXACT PROMPT + examples)
└── references/
├── why-it-works.md
└── before-after-examples.md
Safety Tool Structure
skill-name/
├── SKILL.md (threat model + risk tiers + rules)
└── references/
├── risk-classification.md
└── override-mechanisms.md
Orchestration Structure
skill-name/
├── SKILL.md (quick start + core commands)
├── references/
│ ├── robot-mode-api.md
│ └── integrations.md
└── scripts/
└── automation-helpers.sh
Phase 5: Write the Description (Most Critical)
Apply these rules:
- Third person always ("Processes files" not "I help you")
- Include WHAT it does AND WHEN to trigger
- Specific trigger phrases users would say
- Max 1024 characters
Use this template:
description: >-
[What it does - actions, capabilities].
Use when [trigger phrases, contexts, file types, user intents].
Phase 6: Create the Skill
CRITICAL: Use AskUserQuestion to ask where the skill should be saved.
Use the AskUserQuestion tool with these options:
Question: "Where should this skill be saved?"
Header: "Location"
Options:
1. Label: "Personal (home folder)"
Description: "Save to ~/.claude/skills/<skill-name>/ - Available in all projects for this user"
2. Label: "Project folder"
Description: "Save to .claude/skills/<skill-name>/ in current working directory - Project-specific skill"
3. Label: "Existing plugin"
Description: "Add to an existing plugin in this project - For plugin development"
After the user selects their preference, set the --path argument accordingly:
- Personal:
--path ~/.claude/skills - Project:
--path .claude/skills(relative to current working directory) - Plugin: Ask which plugin, then use
--path plugins/<plugin-name>/skills
Option A: Use init_skill.py (Recommended)
Run the initialisation script to scaffold the skill structure:
python ${CLAUDE_PLUGIN_ROOT}/skills/skill-mastery/scripts/init_skill.py <skill-name> --path <location>
Then customise the generated files:
- Edit SKILL.md - replace TODO placeholders
- Customise or delete example files in scripts/, references/, assets/
Option B: Manual Creation
Create the skill structure using Write tool:
- Create directory structure
- Write SKILL.md with:
- Proper frontmatter (verified against latest API)
- Lean body (<500 lines, ~2,000 words)
- Progressive disclosure (pointers to references)
- Create reference files for detailed content
- Create scripts if needed (execute, don't load)
Phase 7: Validate Quality
Use the skill-reviewer agent from plugin-dev:
Use the Task tool to launch the skill-reviewer agent to review the skill at [path].
Check: description quality, progressive disclosure, writing style, token efficiency.
Apply the Quick Reference checklist:
- name: lowercase, hyphens, ≤64 chars
- description: third person, specific triggers, ≤1024 chars
- SKILL.md body: <500 lines
- References: one level deep
- Consistent terminology
- Examples concrete, not abstract
Phase 8: Test and Iterate
Guide user through testing:
- Test triggering: Ask questions using trigger phrases
- Test content: Does guidance apply correctly?
- Test references: Do they load when needed?
- Test with fresh context: Start new conversation, try skill
If issues found, iterate on the skill and re-validate.
Phase 9: Package for Distribution (Optional)
If the user wants to share the skill, use the packaging script:
python ${CLAUDE_PLUGIN_ROOT}/skills/skill-mastery/scripts/package_skill.py <path/to/skill> [output-dir]
This validates the skill and creates a distributable zip file.
Summary
When complete, provide:
- Skill location
- How to trigger it
- What it does
- Token efficiency estimate (metadata + SKILL.md size)
- Package location (if packaged)
- Suggestions for improvement
Notes
- Always use British English spelling (analyse, optimise, behaviour)
- Never use emdashes - use hyphens with spaces instead
- Validate against latest API before finalising frontmatter
- Prefer progressive disclosure over inline content
- Test with the actual trigger phrases in description