name: design-skill
description: Guide for designing skills. Use when creating new skills, refactoring existing ones, or reviewing skill architecture.

Skills Design Guide

Skills are abstractions — just like in software development.

Skill Types (Abstraction Levels)

Design Principles

1. DRY — Don't Repeat Yourself

If 3+ skills share the same pattern, extract to a reference skill.

Examples:
- Browser automation → chrome-automation
- LLM tool selection → llm-routing (TODO)
- Vault file paths → vault-pathfinding (TODO)

2. Chain, Don't Duplicate

Skills should call other skills, not copy their logic.

/review-saved-jobs
  └── chains to /evaluate-job
        └── chains to /judge

3. Reference, Don't Inline

Link to reference skills instead of inlining best practices.

## Related Skills
- `chrome-automation` — Browser best practices

4. Descriptions Carry Instructions

Skill descriptions are seen by all agents. Put "MUST do X" in the description rather than repeating in each agent's instruction file (CLAUDE.md, TOOLS.md, etc). Saves tokens.

Example: /skill-sync description says "MUST run after creating skills" — no need to repeat in CLAUDE.md.

5. Close Feedback Loops

Outputs from one skill should feed back into related skills.

/debrief → captures interview signals
    ↓
/evaluate-job → uses signals to flag anti-patterns
    ↓
/interview-prep → incorporates learnings

6. Naming: Verb-First for Actions

• Action skills → verb-first: evaluate-job, sync-skills, design-skill
• Trigger/lookup skills → short nouns fine: todo, hko, morning

Skill Clusters

Job Hunting

evaluate-job ←→ review-saved-jobs
     ↓              ↓
   judge      chrome-automation
     ↓
  debrief ←→ counter-intel
     ↓
interview-prep → ai-news

Content Extraction

evaluate-article
wechat-article     → content-fetch (TODO)
youtube-transcript
pdf-extract

LLM Querying

ask-llms ←→ llm-routing (TODO) ←→ llm-council
                ↓
            remote-llm

Reference Skill Template

---
name: skill-name
description: Reference for X. Not user-invocable — use as internal guidance.
user_invocable: false
---

# Skill Name

One-line purpose.

## When to Use

- Bullet points

## Patterns

| Pattern | Use Case |
|---------|----------|
| ... | ... |

## Gotchas

| Issue | Solution |
|-------|----------|
| ... | ... |

## Related Skills

- `other-skill` — How it relates

TODO: Reference Skills to Create

Audit Findings (Jan 31, 2026)

High Priority:
- [x] Create vault-pathfinding reference ✓
- [x] Create llm-routing reference ✓
- [x] Add feedback loop: debrief signals → evaluate-job ✓

Medium Priority:
- [ ] Create content-fetch reference
- [ ] Add /ai-news reference to interview-prep
- [ ] Consolidate job-hunt skills documentation

Low Priority:
- [ ] Add user_invocable: false to judge, plan, history
- [ ] Add cross-references in skill descriptions