Skill Authoring

---
name: skill-authoring
domain: meta
description: |
  [METHODOLOGY] Guide for creating/updating skills with specialized
  knowledge and workflows. Pure reference — invoked via slash command or
  explicit Skill tool call, not auto-triggered by keywords.
---

# Skill Creator

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

## Skill Types

There are two types of skills based on how they guide Claude's work.

### Procedural Skills

Use when the task requires a strict sequence of steps where order matters. Phase 2 depends on Phase 1 completing correctly. Skipping or reordering steps would break the workflow.

Examples: code-writing (Plan → TDD → Review), project-planning (Interview → Features → Roadmap), tech-spec-planning.

These skills have explicit phases with checkpoints after each phase to verify completion before proceeding.

**Creating a procedural skill?** Read [procedural-skills.md](references/procedural-skills.md) — phase structure, checkpoints, verification patterns.

### Informational Skills

Use when providing methodology, knowledge, or guidelines without a strict execution order. The agent reads relevant sections and applies them to the situation. There's no "Phase 1 must complete before Phase 2" — sections are independent.

Examples: security-auditing (what to check), testing (when to use which test type), company-info (domain knowledge), database-schemas.

These skills organize content into logical sections with decision frameworks (YES if / NO if) to help the agent choose what applies.

**Creating an informational skill?** Read [informational-skills.md](references/informational-skills.md) — section organization, knowledge structure.

## 1. Discovery

For new skills or major changes — run discovery interview:
- What problem does the skill solve?
- What phrases should trigger it?
- What should the skill NOT do?
- Concrete usage examples

**When running user interview**, read [interview-guide.md](references/interview-guide.md) — process overview, example questions for each phase, handling "I don't know" answers.

## 2. Skill Structure

### Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   ├── description: (required)
│   │   └── domain: (required — one of: marketing, dev, design, meta)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

### Frontmatter

**`name`** (required):
- kebab-case (lowercase, hyphens)
- ≤64 characters
- Unique identifier

**`description`** (required):
- Third person ("Analyzes code...", NOT "I analyze...")
- Include both WHAT the skill does AND WHEN to use it
- ≤1024 characters

**`domain`** (required):
- One of: `marketing`, `dev`, `design`, `meta`
- Three work domains each have one Director skill (`marketing-director`, `dev-director`, `design-director`) that orchestrates leads and specialists in that domain.
- `meta` has no director — system-maintenance utilities.
- Used by `regen_catalog.py` to group skills in `~/.claude/SKILLS.md`
- Used by `lint_skill.py` to detect missing/invalid domain

#### Description Best Practices

Claude uses description to decide when to auto-invoke the skill. Be specific and include key terms.

**Template:**
```yaml
description: |
  [What the skill does — be specific, include key terms]

  Use when: [trigger conditions — specific phrases users say]
```

**Rules:**
1. **Be specific** — Include key terms that match user requests
2. **List trigger phrases** — Real phrases users actually say (5-10 phrases)
3. **Include variations** — "техспек" AND "составь тз" (different ways to say same thing)

**Bad:**
```yaml
description: This skill helps with documents. Use when user wants to work with docs.
```
Why bad: Vague phrases ("work with docs"), no specific triggers.

**Good:**
```yaml
description: |
  Manage .claude/skills/project-knowledge/ docs: create, check, update.

  Use when: "заполни документацию", "создай документацию", "проверь документацию", "обнови документацию"
```
Why good: Specific actions, concrete trigger phrases.

**How to gather trigger phrases:**
1. Think: "What would I actually say to invoke this skill?"
2. Ask: "How would different users phrase this request?"
3. Include: Common typos, informal variants, both Russian and English if applicable

For optional fields, see [frontmatter-options.md](references/frontmatter-options.md) — argument-hint, disable-model-invocation, allowed-tools, model override.

### Body

Every SKILL.md body consists of:
- **Core workflow** — main instructions that are always needed
- **Links to references** — for optional/detailed information
- Keep under 500 lines (otherwise → split to references)

**When defining output format**, read [output-patterns.md](references/output-patterns.md) — template pattern, examples pattern.

### Bundled Resources

A skill contains only SKILL.md and these three optional directories — nothing else (no README, CHANGELOG, etc.).

#### Scripts (`scripts/`)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments

**Concrete example:** When building a `pdf-editor` skill for queries like "Help me rotate this PDF":
1. Rotating a PDF requires re-writing the same code each time
2. A `scripts/rotate_pdf.py` script solves this — write once, execute many times

#### References (`references/`)

Content needed in some execution paths, not all. If the skill branches (multiple operations, domains, modes) — each branch's details go to a reference. Content needed on every execution stays in SKILL.md.

**Example:** Task-management skill handles "create" and "edit". Each operation's workflow → separate reference. Task file format used by both → stays in SKILL.md.

- **No duplication**: Content lives in either SKILL.md or references, not both

**How to link references in SKILL.md:**

Embed references in workflow where they're logically needed. Two linking patterns, ranked by strength:

**Pattern A: Action-embedded (strong)** — the workflow step's action IS applying the reference content. The agent cannot complete the step without loading the file.

```markdown
3. Write tests following patterns from [testing-guide.md](references/testing-guide.md)
   (test structure, naming, what to skip)

4. Apply audit criteria from [principles.md](references/principles.md) to each file
   (code examples, obvious content, generic explanations)
```

Why it works: "follow patterns from X" or "apply criteria from X" makes the reference part of the action, not a separate read-then-do instruction.

**Pattern B: Condition + contents (basic)** — for optional references needed only in specific scenarios. Each link explains WHEN to read and WHAT's inside.

```markdown
**For tracked changes**, see [REDLINING.md] — revision marks, accept/reject.
**First time with docx-js?** Read [DOCX-JS.md] — setup, examples, pitfalls.
```

Use Pattern A for references that contain rules/patterns the agent must follow during a step. Use Pattern B for references that are only relevant in certain branches of the workflow.

**Anti-pattern: Resource catalog at end of file.** A passive list of references separated from the workflow. The agent reads the workflow top-down, gets instructions, and treats the catalog as optional appendix.

```markdown
❌ Bad — passive catalog (ignored):
## Resources
### references/structure.md
Complete description of all files...
### references/principles.md
Quality principles...

✅ Good — embed each reference into the workflow step where it's needed:
4. Apply audit criteria from [principles.md](references/principles.md) to each file
```

**Bad** (passive, no trigger):
- `Detailed guide: [X.md]`
- `See [X.md] for details`
- `Finance: [finance.md]` (no context why to read)

**Good** (embedded in action or conditional):
- `3. Write tests following patterns from [testing-guide.md]` (action-embedded)
- `**Working with finance?** Read [finance.md] — P&L rules, ARR formulas` (conditional)
- `4. Apply criteria from [principles.md] to each file` (action-embedded)

#### Assets (`assets/`)

Files not intended to be loaded into context, but rather used within the output Claude produces.

- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context

**Concrete example:** When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app":
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An `assets/hello-world/` template with boilerplate project files solves this — copy and customize

## 3. Writing Guidelines

### Concise is Key

The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

### Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

### Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. **Metadata (name + description)** — Always in context (~100 words)
2. **SKILL.md body** — When skill triggers (<5k words)
3. **Bundled resources** — As needed by Claude (unlimited, scripts execute without reading)

Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit. When splitting, reference them from SKILL.md and describe clearly when to read them.

**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate reference files.

**Pattern 1: High-level guide with references**

```markdown
# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features

**For form filling?** Read [FORMS.md](FORMS.md) — interactive fields, validation, PDF/A.

For complete API reference, see [REFERENCE.md](REFERENCE.md) — all methods with examples.
```

Claude loads FORMS.md or REFERENCE.md only when needed.

**Pattern 2: Domain-specific organization**

For skills with multiple domains, organize content by domain:

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    └── product.md (API usage, features)
```

In SKILL.md, link each domain with description:

**When working with finance data**, read [finance.md](references/finance.md) — P&L rules, revenue calculations, ARR formulas.

For sales data analysis, see [sales.md](references/sales.md) — opportunity stages, pipeline calculations, account hierarchies.

**Working with product metrics?** Read [product.md](references/product.md) — API usage tracking, feature adoption, user segments.

**Pattern 3: Conditional details**

```markdown
# DOCX Processing

## Creating documents
Use docx-js for basic operations.

**First time with docx-js?** Read [DOCX-JS.md](DOCX-JS.md) — setup, examples, pitfalls.

## Editing documents
For simple edits, modify XML directly.

For tracked changes, see [REDLINING.md](REDLINING.md) — revision marks, accept/reject logic.
```

**Important guidelines:**
- Keep references one level deep from SKILL.md
- For files longer than 100 lines, include a table of contents at the top

### Positive over Negative

Claude follows positive instructions better. Negative ("don't do X") often ignored.

**Bad:** "Don't use bullet points. Never include examples. Avoid long explanations."
**Good:** "Write in prose paragraphs. Keep explanations to 2-3 sentences."

### Add Motivation

When Claude understands WHY a rule matters, it follows more reliably.

**Bad:** "Always return JSON format."
**Good:** "Return findings as JSON. Reason: orchestrator parses this automatically. Invalid JSON crashes pipeline."

### Avoid Emphasis Words

Words like CRITICAL, MANDATORY, NEVER, IMPORTANT, MUST are anti-patterns in skills.

**Why they don't work:**
- Every instruction in a skill is already important — if it wasn't, it shouldn't be there
- When everything is emphasized — nothing stands out
- Emphasis words signal poorly written instructions that need rewriting, not shouting

**What to do instead:**
- Write clear, specific instructions
- Add motivation (WHY something matters)
- Use structure (steps, checkpoints) to ensure compliance

**Hard limit:** Maximum one emphasis word per skill. Ideal: zero.

### Delegating Heavy Work

If skill has context-heavy tasks (reviews, research, validation):
- Don't put everything in one skill
- Create separate skills for methodology
- Create agents that preload these skills
- Orchestrator calls agents → they work isolated → return results

**When to use subagents:**
- **Reviews** — code-reviewer, security-auditing, test-reviewer check work with fresh context
- **Research** — exploring codebase, reading documentation, searching information
- **Debugging** — isolated context for error diagnosis and root cause analysis
- **Validation** — checking schemas, formats, requirements compliance
- **Parallel tasks** — multiple independent investigations simultaneously
- **High-volume output** — tests, logs, reports that would bloat main context

**Two approaches:**

1. **Inline prompts** — for simple, one-off tasks (<50 lines):
   ```
   Use general-purpose/explore/plan subagent to find all TypeScript files importing {module}
   ```

2. **Skill + Agent pattern** — for complex, reusable tasks (>50 lines):
   - **Skill** holds methodology (WHAT to do, HOW to analyze)
   - **Agent** adds isolation + output format (runs in isolated context)
   - Agent uses `skills:` field to preload methodology
   - Reference by name: "Use `code-reviewer` agent"

**Key principle:** Keep detailed agent prompts out of SKILL.md. Large prompts bloat the skill and waste context. Store specialized agent definitions separately; the skill just invokes them.

**Delegating work to subagent?** Read [agents.md](references/agents.md) — inline prompts, dedicated agents, output contracts.

## 4. Validation

### Run skill-checker

After self-check — run validation:

```
Use skill-checker subagent to validate the skill at {path}.
If issues found → fix them → run skill-checker again.
```

skill-checker is defined in `~/.claude/agents/skill-checker.md` and has skill-authoring preloaded.

### Self-Check Before Validation

**Universal (all skills):**
- [ ] name in kebab-case, ≤64 chars
- [ ] description < 1024 chars, includes "Use when:" with trigger phrases
- [ ] domain set to valid slug (marketing / dev / design / meta)
- [ ] SKILL.md < 500 lines
- [ ] All referenced files exist
- [ ] No extra docs (README, CHANGELOG)
- [ ] References contain only conditional content (not needed on every execution path)
- [ ] References linked as action steps or with condition + contents (no passive links, no resource catalogs at end of file)
- [ ] Uses positive instructions (not "don't do X")
- [ ] No emphasis words (CRITICAL, MANDATORY, NEVER) — max one allowed

**Identify skill type:** procedural or informational?

**If Procedural:**
- [ ] Has explicit phases with numbered steps
- [ ] Has checkpoints after each phase
- [ ] Has self-verification section at end
- [ ] Uses subagent verification for critical operations (if applicable)

**If Informational:**
- [ ] Sections organized by logic, not sequence
- [ ] Decision frameworks present (YES if / NO if) where applicable
- [ ] No forced sequential structure

**Functional (all skills):**
- [ ] Run skill-checker and fix all issues
- [ ] Run portfolio lint: `python ~/.claude/skills/skill-authoring/scripts/lint_skill.py --file <path>/SKILL.md` — fix errors, review warnings
- [ ] Regenerate catalog: `python ~/.claude/skills/skill-authoring/scripts/regen_catalog.py` — refreshes `~/.claude/SKILLS.md`

## Portfolio Hygiene

As the skill portfolio grows, three scripts in `scripts/` keep it navigable and collision-free:

### 1. Before creating a new skill — lint the proposal

Check name uniqueness, trigger-phrase overlap with existing skills, and required frontmatter fields:

```bash
python ~/.claude/skills/skill-authoring/scripts/lint_skill.py \
  --name my-new-skill \
  --domain meta \
  --description "Does X. Use when: 'trigger phrase 1', 'trigger phrase 2'"
```

Exit codes: 0 = clean, 1 = warnings (review), 2 = errors (fix before creating).

### 2. After creating — validate the real file

```bash
python ~/.claude/skills/skill-authoring/scripts/lint_skill.py \
  --file ~/.claude/skills/my-new-skill/SKILL.md
```

### 3. Regenerate catalog

```bash
python ~/.claude/skills/skill-authoring/scripts/regen_catalog.py
```

Reads `domain:` from every `SKILL.md` frontmatter and rewrites the section between `<!-- SKILLS_INDEX:START -->` and `<!-- SKILLS_INDEX:END -->` in `~/.claude/SKILLS.md`. Everything outside the markers is preserved.

### 4. Portfolio-wide health check

Periodically lint every skill to catch drift (missing domain, accidental name collisions, growing trigger overlaps):

```bash
python ~/.claude/skills/skill-authoring/scripts/lint_skill.py --all
```

### When to split into plugins

At 40 skills, flat structure with domain tags works. If the portfolio passes ~100 skills AND you start sharing domain clusters (e.g. publishing marketing-suite), consider extracting into Claude Code plugins. The domain slug becomes the plugin name, trigger becomes `plugin:skill`. Until then, flat + domain-tagged + auto-catalog is lower overhead.