| name | building-skills |
| description | Build production-ready Claude Code skills through a structured Research-Draft-Refine process. Use when creating new skills, converting slash commands to skills, or generating AgentSkills.io-compatible skills from specifications. |
| argument-hint | <description or @spec-file> [--format claude|agentskills|both] [--depth light|normal|deep] |
| disable-model-invocation | true |
| allowed-tools | Task, Read, Write, MultiEdit, Bash(mkdir:*), Glob, Grep, WebFetch |
Building Skills
Build production-ready skills through a 3-phase process: Research, Draft, Refine.
Supported Output Formats
- Claude Code skills (
.claude/skills/<name>/SKILL.md) - current standard with invocation control, subagent execution, hooks
- AgentSkills.io skills - portable cross-agent format following the open standard
Input
$ARGUMENTS - skill specification: natural language description, @filepath to a spec file, or name: description format--format - output format: claude (default), agentskills, or both--depth - research depth: light (2-3 sources), normal (5 sources, default), deep (8-10 sources)--dry-run - preview the execution plan without creating files
Multiple skills can be specified separated by spaces. Use comma-separated --depth values for per-skill depth.
Process Overview
- Parse input and configure
- Phase 1: Research
- Phase 2: Draft
- Phase 3: Refine and validate
- Write files and summarize
Step 1: Parse Input and Configure
Determine what skills to build and how.
Parse specifications:
- If input starts with
@, read the referenced file as the spec
- If input contains
name: description, split on first colon
- Otherwise, generate a kebab-case name from the description
Parse flags:
- Extract
--format, --depth, --dry-run from arguments
- Default format:
claude
- Default depth:
normal
Dry run: If --dry-run, print the execution plan (skill names, formats, depths, output paths) and stop.
Confirm with user: Present the plan and ask for approval before proceeding. Show:
- Skill name(s) and description(s)
- Output format(s) and location(s)
- Research depth
Wait for explicit user confirmation before continuing.
Step 2: Phase 1 - Research
Launch one Task agent per skill specification, concurrently. Each agent's prompt should include the skill's purpose, the target format(s), and the research depth setting.
The research prompt should direct the agent to investigate:
- Similar existing skills and their patterns
- Domain knowledge needed for the skill's purpose
- Appropriate invocation model (who triggers it, does it need isolation?)
- Tool permissions needed (minimal and specific)
- Whether supporting files would help (progressive disclosure)
- Error handling patterns for the domain
Include the contents of references/format-spec.md in each research prompt so agents understand both output formats.
Launch all research agents in a single response for concurrent execution.
Collect results before proceeding to Phase 2.
Step 3: Phase 2 - Draft
Launch one Task agent per skill and format combination, concurrently. Each agent's prompt should include the research report from Phase 1 and the complete format specification from references/format-spec.md. The agent must produce all files for the skill directory.
Critical drafting rules:
- SKILL.md must be under 500 lines
- Description must state WHAT the skill does AND WHEN to use it
- Description must include trigger keywords for auto-discovery
- Tool permissions must be specific (
Bash(git:*) not Bash)
- Supporting files referenced from SKILL.md with relative paths
- No secrets, credentials, or time-sensitive information
- Professional language (no slang in generated content)
Invocation control decision:
- Side-effect skills (deploy, commit, send):
disable-model-invocation: true
- Background knowledge (conventions, patterns):
user-invocable: false
- Isolated/heavy tasks:
context: fork with appropriate agent
- Most skills: default (both user and Claude can invoke)
Launch all Task agents in a single response for concurrent execution.
Collect results before proceeding to Phase 3.
Step 4: Phase 3 - Refine and Validate
Review each drafted skill against the quality checklist. Reference quality-checklist.md for the complete validation criteria.
Core validation:
Format-specific validation:
For Claude Code skills:
For AgentSkills.io skills:
Fix any issues found during validation.
Step 5: Write Files and Summarize
Create the skill directory:
apps/dot-claude/skills/<skill-name>/
├── SKILL.md
├── [supporting files as needed]
Write all files using the Write tool.
Validate the written files:
- Read back SKILL.md and verify frontmatter parses correctly
- Confirm line count is under 500
- Verify all referenced supporting files exist
Present summary to user:
## Skill Build Summary
| Skill | Format | Location | Invocation |
|-------|--------|----------|------------|
| name | format | path | mode |
### Files Created
- [list all files with paths]
### Next Steps
- Review generated skill(s)
- Test with representative inputs
- Deploy to ~/.claude/skills/ (personal) or .claude/skills/ (project)
Error Handling
- Research fails: Continue with general best practices, note limited context
- Draft fails: Retry once with simplified prompt; if still fails, report and skip
- Validation fails: Fix issues in-place; if unfixable, report to user
- Partial success: Report which skills succeeded and which failed
Additional Resources
