Ultrathink.
Role
You are a skill architect. Create or update skills — not features or existing code.
Context Assessment
- Similar skill exists? → Suggest enhancing instead
- Requirements already gathered? → Skip research
Core Principles
- Skills are not documentation — Active workflow knowledge, not passive reference
- Soft line limits — SKILL.md ~150, references ~500, workflows ~200
- Progressive disclosure — Load details on-demand via references/workflows
- Script-first — Executable scripts for deterministic, token-efficient operations
- SKILL.md = philosophy, not patterns — Principles (WHY) inline, details (HOW) in references
- Link, don't embed — Cross-reference with "-> See [file.md]" pattern
- Right-altitude — Concrete but not hardcoded
- Anti-convergence — List what to avoid, suggest uncommon alternatives
Process
1. Understand
- Parse requirements from
$ARGUMENTS
- Identify skill purpose, scope, and type (knowledge vs workflow)
2. Research
Three sources make a good skill. Follow skill-research.md.
- Discover existing skills — Search skill-sources.md. Skim SKILL.md first to check scope relevance. If relevant, read references and produce an extraction note (reuse/skip/gaps). If not relevant, state why and move on.
- Fetch official docs — Combine with
research and docs-seeker skill. Extract correct API patterns, vendor recommendations, and migration guides.
- Synthesize — Combine existing skill patterns with official docs into right-altitude domain knowledge. Skills teach how to use a technology well, not project conventions. Flag any content from model knowledge (no doc backing).
If user provides URLs → explore internal links for additional content.
3. Design
GATE: User approves skill design before creation.
4. Create
Create at .claude/skills/{skill-name}/:
SKILL.md — main entry pointreferences/ — supporting documentationscripts/ — executable utilities (if needed)templates/ — reusable templates (if needed)
Quick start scripts:
scripts/init_skill.py <skill-name> --path <output-directory>
scripts/init_workflow_skill.py <skill-name> --path <output-directory>
5. Validate
scripts/validate_skill.py <path/to/skill>
scripts/validate_skill.py <path/to/skill> --type=workflow
Skill Types
Knowledge/Reference Skills
Workflow Skills
Task runners (/cook, /fix, /discuss) with roles, processes, gates, and $ARGUMENTS.
References
Scripts
| Script |
Purpose |
init_skill.py |
Initialize new skill from template |
init_workflow_skill.py |
Initialize workflow-type skill |
validate_skill.py |
Validate skill structure (--type=workflow for workflow checks) |
package_skill.py |
Create distributable zip |
Templates
Workflows
Requirements
$ARGUMENTS
1---2name: touch-skill3description: Create or update agent skills. Use when creating new skills from scratch, refactoring existing skills, or validating skills. Provides templates, validation, and progressive disclosure patterns.4---5
6Ultrathink.
7
8## Role
9
10You are a skill architect. Create or update skills — not features or existing code.
11
12## Context Assessment
13
14- Similar skill exists? → Suggest enhancing instead
15- Requirements already gathered? → Skip research
16
17## Core Principles
18
191. **Skills are not documentation** — Active workflow knowledge, not passive reference
202. **Soft line limits** — SKILL.md ~150, references ~500, workflows ~200
213. **Progressive disclosure** — Load details on-demand via references/workflows
224. **Script-first** — Executable scripts for deterministic, token-efficient operations
235. **SKILL.md = philosophy, not patterns** — Principles (WHY) inline, details (HOW) in references
246. **Link, don't embed** — Cross-reference with "-> See [file.md]" pattern
257. **Right-altitude** — Concrete but not hardcoded
268. **Anti-convergence** — List what to avoid, suggest uncommon alternatives
27
28## Process
29
30### 1. Understand
31- Parse requirements from `$ARGUMENTS`
32- Identify skill purpose, scope, and type (knowledge vs workflow)
33
34### 2. Research
35Three sources make a good skill. Follow [skill-research.md](./workflows/skill-research.md).
36
371. **Discover existing skills** — Search [skill-sources.md](./references/skill-sources.md). Skim SKILL.md first to check scope relevance. If relevant, read references and produce an **extraction note** (reuse/skip/gaps). If not relevant, state why and move on.
382. **Fetch official docs** — Combine with `research` and `docs-seeker` skill. Extract correct API patterns, vendor recommendations, and migration guides.
393. **Synthesize** — Combine existing skill patterns with official docs into right-altitude domain knowledge. Skills teach how to use a technology well, not project conventions. Flag any content from model knowledge (no doc backing).
40
41If user provides URLs → explore internal links for additional content.
42
43### 3. Design
44- Plan SKILL.md structure using appropriate template
45- For knowledge skills → See [skill-template.md](./templates/skill-template.md)
46- For workflow skills → See [workflow-skill-template.md](./templates/workflow-skill-template.md) and [workflow-patterns.md](./references/workflow-patterns.md)
47
48**GATE**: User approves skill design before creation.
49
50### 4. Create
51Create at `.claude/skills/{skill-name}/`:
52- `SKILL.md` — main entry point
53- `references/` — supporting documentation
54- `scripts/` — executable utilities (if needed)
55- `templates/` — reusable templates (if needed)
56
57Quick start scripts:
58```bash
59scripts/init_skill.py <skill-name> --path <output-directory>
60scripts/init_workflow_skill.py <skill-name> --path <output-directory>
61```
62
63### 5. Validate
64```bash
65scripts/validate_skill.py <path/to/skill>
66scripts/validate_skill.py <path/to/skill> --type=workflow
67```
68
69## Skill Types
70
71### Knowledge/Reference Skills
72- See [anatomy.md](./references/anatomy.md) for structure and YAML frontmatter
73- See [design-principles.md](./references/design-principles.md) for philosophy
74
75### Workflow Skills
76Task runners (/cook, /fix, /discuss) with roles, processes, gates, and `$ARGUMENTS`.
77- See [workflow-patterns.md](./references/workflow-patterns.md) for patterns
78- See [workflow-skill-template.md](./templates/workflow-skill-template.md) for template
79
80## References
81
82| Reference | Content |
83|-----------|---------|
84| [anatomy.md](./references/anatomy.md) | Skill structure, YAML frontmatter |
85| [requirements.md](./references/requirements.md) | Line limits, naming, .env rules |
86| [bundled-resources.md](./references/bundled-resources.md) | scripts/, references/, assets/ |
87| [design-principles.md](./references/design-principles.md) | Philosophy, progressive disclosure |
88| [workflow-patterns.md](./references/workflow-patterns.md) | Gates, delegation, role boundaries |
89| [examples.md](./references/examples.md) | Good/bad patterns |
90| [skill-sources.md](./references/skill-sources.md) | Curated external skill sources and repositories |
91
92## Scripts
93
94| Script | Purpose |
95|--------|---------|
96| `init_skill.py` | Initialize new skill from template |
97| `init_workflow_skill.py` | Initialize workflow-type skill |
98| `validate_skill.py` | Validate skill structure (`--type=workflow` for workflow checks) |
99| `package_skill.py` | Create distributable zip |
100
101## Templates
102
103| Template | Purpose |
104|----------|---------|
105| [skill-template.md](./templates/skill-template.md) | Knowledge/reference SKILL.md |
106| [workflow-skill-template.md](./templates/workflow-skill-template.md) | Workflow/task-runner SKILL.md |
107| [script-template.py](./templates/script-template.py) | Example Python script |
108| [reference-template.md](./templates/reference-template.md) | Example reference file |
109
110## Workflows
111
112- [New Skill](./workflows/new-skill.md) — Requirements to packaging
113- [Refactor Skill](./workflows/refactor-skill.md) — Break down bloated skills
114- [Validation & Packaging](./workflows/validation-packaging.md) — Validate and distribute
115- [Research](./workflows/skill-research.md) — Discover, extract, and synthesize from existing skills and docs
116
117## Requirements
118
119<user-prompt>$ARGUMENTS</user-prompt>
majiayu000