From c9a72bf1d3c9743b7381d684f9746f49a3ed411d Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 10 Jan 2026 15:42:50 +0100 Subject: [PATCH] Add capability-writing skill with templates and design guidance Creates a skill that teaches how to design and create capabilities (skill + command + agent combinations) for the architecture repository. Includes: - Component templates for skills, commands, and agents - Decision tree and matrix for when to use each component - Model selection guidance (haiku/sonnet/opus) - Naming conventions and anti-patterns to avoid - References to detailed documentation in docs/ - Checklists for creating each component type Closes #74 Co-Authored-By: Claude Opus 4.5 --- skills/capability-writing/SKILL.md | 424 +++++++++++++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 skills/capability-writing/SKILL.md diff --git a/skills/capability-writing/SKILL.md b/skills/capability-writing/SKILL.md new file mode 100644 index 0000000..6c3bdb8 --- /dev/null +++ b/skills/capability-writing/SKILL.md @@ -0,0 +1,424 @@ +--- +name: capability-writing +description: > + Guide for designing and creating capabilities for the architecture repository. + A capability is a cohesive set of components (skill + command + agent). + Use when creating new skills, commands, or agents, or when extending the + AI workflow system. Includes templates, design guidance, and conventions. +user-invocable: false +--- + +# Capability Writing + +How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together. + +## Component Overview + +| Component | Location | Purpose | Example | +|-----------|----------|---------|---------| +| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture | +| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue | +| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer | + +## When to Use Each Component + +### Decision Tree + +``` +Start here: What do you need? + | + +--> Just knowledge to apply automatically? + | --> Skill only + | + +--> User-initiated workflow using existing knowledge? + | --> Command (reference skills via @) + | + +--> Complex isolated work needing focused context? + | --> Command + Agent (agent uses skills) + | + +--> New domain expertise + workflow + isolated work? + --> Full capability (all three) +``` + +### Decision Matrix + +| Need | Component | Example | +|------|-----------|---------| +| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing | +| User-invoked workflow | Command | /work-issue, /dashboard | +| Isolated subtask with focused context | Agent | code-reviewer, issue-worker | +| All three working together | Full capability | arch-review (skill + command + agent) | + +### Signs You Need Each Component + +**Create a Skill when:** +- You explain the same concepts repeatedly +- Quality is inconsistent without explicit guidance +- Multiple commands need the same knowledge +- There is a clear domain that does not fit existing skills + +**Create a Command when:** +- Same workflow is used multiple times +- User explicitly triggers the action +- Approval checkpoints are needed +- Multiple tools need orchestration + +**Create an Agent when:** +- Task requires deep exploration that would pollute main context +- Multiple skills work better together +- Batch processing or parallel execution is needed +- Specialist persona improves outputs + +## Component Templates + +### Skill Template + +Location: `skills//SKILL.md` + +```yaml +--- +name: skill-name +description: > + What this skill teaches and when to use it. + Include trigger conditions in description (not body). + List specific capabilities users would mention. +user-invocable: false +--- + +# Skill Name + +Brief description of what this skill covers. + +## Core Concepts + +Explain fundamental ideas Claude needs to understand. + +## Patterns and Templates + +Provide reusable structures and formats. + +## Guidelines + +List rules, best practices, and quality standards. + +## Examples + +Show concrete illustrations of the skill in action. + +## Common Mistakes + +Document pitfalls to avoid. + +## Reference + +Quick-reference tables, checklists, or commands. +``` + +**Frontmatter fields:** + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Lowercase, hyphens, matches directory name | +| `description` | Yes | What it does + when to use (max 1024 chars) | +| `user-invocable` | No | Set `false` for reference-only skills | +| `model` | No | Specific model: `haiku`, `sonnet`, `opus` | +| `context` | No | Use `fork` for isolated context | +| `allowed-tools` | No | Restrict available tools | + +### Command Template + +Location: `commands/.md` + +```yaml +--- +description: What this command does (one-line summary) +argument-hint: [optional] +model: sonnet +--- + +# Command Title + +@~/.claude/skills/relevant-skill/SKILL.md + +1. **First step**: What to do +2. **Second step**: What to do next +3. **Ask for approval** before significant actions +4. **Execute** the approved actions +5. **Present results** with links and summary +``` + +**Frontmatter fields:** + +| Field | Required | Description | +|-------|----------|-------------| +| `description` | Yes | One-line summary for help/listings | +| `argument-hint` | No | Shows expected args: ``, `[optional]` | +| `model` | No | Override model: `haiku`, `sonnet`, `opus` | +| `context` | No | Use `fork` for isolated context | +| `allowed-tools` | No | Restrict available tools | + +### Agent Template + +Location: `agents//AGENT.md` + +```yaml +--- +name: agent-name +description: What this agent does and when to spawn it +model: sonnet +skills: skill1, skill2 +disallowedTools: + - Edit + - Write +--- + +You are a [role] specialist that [primary function]. + +## When Invoked + +Describe the process the agent follows: + +1. **Gather context**: What information to collect +2. **Analyze**: What to evaluate +3. **Act**: What actions to take +4. **Report**: How to communicate results + +## Output Format + +Describe expected output structure. + +## Guidelines + +- Behavioral rules +- Constraints +- Quality standards +``` + +**Frontmatter fields:** + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Lowercase, hyphens, matches directory name | +| `description` | Yes | What it does + when to spawn | +| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` | +| `skills` | No | Comma-separated skill names (not paths) | +| `disallowedTools` | No | Tools to block (e.g., Edit, Write for read-only) | +| `permissionMode` | No | `default` or `bypassPermissions` | + +## Model Selection Guidance + +| Model | Use When | Examples | +|-------|----------|----------| +| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap | +| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer | +| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor | + +### Decision Criteria + +- **Start with `sonnet`** - handles most tasks well +- **Use `haiku` for volume** - speed and cost matter at scale +- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex +- **Consider the stakes** - higher consequence tasks warrant more capable models + +## Naming Conventions + +### File and Folder Names + +| Component | Convention | Examples | +|-----------|------------|----------| +| Skill folder | kebab-case | `software-architecture`, `issue-writing` | +| Skill file | UPPERCASE | `SKILL.md` | +| Command file | kebab-case | `work-issue.md`, `review-pr.md` | +| Agent folder | kebab-case | `code-reviewer`, `issue-worker` | +| Agent file | UPPERCASE | `AGENT.md` | + +### Naming Patterns + +**Skills:** Name after the domain or knowledge area +- Good: `gitea`, `issue-writing`, `software-architecture` +- Bad: `utils`, `helpers`, `misc` + +**Commands:** Use verb or verb-phrase (actions) +- Good: `work-issue`, `review-pr`, `create-issue` +- Bad: `issue-work`, `pr-review`, `issue` + +**Agents:** Name by role or persona (recognizable specialist) +- Good: `code-reviewer`, `issue-worker`, `software-architect` +- Bad: `helper`, `do-stuff`, `agent1` + +## Referencing Skills + +### In Commands + +Use the `@` file reference syntax to guarantee skill content is loaded: + +```markdown +@~/.claude/skills/gitea/SKILL.md +@~/.claude/skills/issue-writing/SKILL.md +``` + +**Important:** Do NOT use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the content is available. + +### In Agents + +List skill names in the frontmatter (not paths): + +```yaml +--- +name: product-manager +skills: gitea, issue-writing, backlog-grooming +--- +``` + +The agent runtime loads these skills automatically. + +## Common Patterns + +### Approval Workflow (Commands) + +Always ask before significant actions: + +```markdown +4. **Present plan** for approval +5. **If approved**, create the issues +6. **Present summary** with links +``` + +### Conditional Behavior (Commands) + +Handle optional arguments with mode switching: + +```markdown +## If issue number provided ($1): +1. Fetch specific issue +2. Process it + +## If no argument (batch mode): +1. List all issues +2. Process each +``` + +### Spawning Agents from Commands + +Delegate complex subtasks: + +```markdown +9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number +``` + +### Read-Only Agents + +For analysis without modification: + +```yaml +--- +name: code-reviewer +disallowedTools: + - Edit + - Write +--- +``` + +## Anti-Patterns to Avoid + +### Overly Broad Components + +**Bad:** One skill/command/agent that does everything +```markdown +# Project Management +Handles issues, PRs, releases, documentation, deployment... +``` + +**Good:** Focused components with clear responsibility +```markdown +# Issue Writing +How to write clear, actionable issues. +``` + +### Vague Instructions + +**Bad:** +```markdown +1. Handle the issue +2. Do the work +3. Finish up +``` + +**Good:** +```markdown +1. **View the issue** with `--comments` flag +2. **Create branch**: `git checkout -b issue-$1-` +3. **Commit** with message referencing the issue +``` + +### Missing Skill References + +**Bad:** +```markdown +Use the gitea skill to create an issue. +``` + +**Good:** +```markdown +@~/.claude/skills/gitea/SKILL.md + +Use `tea issues create --title "..." --description "..."` +``` + +### God Skills + +**Bad:** Single skill with 1000+ lines covering unrelated topics + +**Good:** Multiple focused skills that reference each other + +### Premature Agent Creation + +**Bad:** Creating an agent for every task + +**Good:** Use agents only when you need: +- Context isolation +- Skill composition +- Parallel execution +- Specialist persona + +## Detailed Documentation + +For comprehensive guides, see the `docs/` directory: + +- `docs/writing-skills.md` - Complete skill writing guide +- `docs/writing-commands.md` - Complete command writing guide +- `docs/writing-agents.md` - Complete agent writing guide + +These documents include: +- Full frontmatter reference +- Annotated examples from the codebase +- Lifecycle management +- Integration checklists + +## Checklists + +### Before Creating a Skill + +- [ ] Knowledge is used in multiple places (not just once) +- [ ] Existing skills do not already cover this domain +- [ ] Content is specific and actionable (not generic) +- [ ] Frontmatter has descriptive `description` with trigger terms +- [ ] File at `skills/<name>/SKILL.md` + +### Before Creating a Command + +- [ ] Workflow is repeatable (used multiple times) +- [ ] User explicitly triggers it (not automatic) +- [ ] Clear start and end points +- [ ] Skills referenced via `@~/.claude/skills/<name>/SKILL.md` +- [ ] Approval checkpoints before significant actions +- [ ] File at `commands/<name>.md` + +### Before Creating an Agent + +- [ ] Built-in agents (Explore, Plan) are not sufficient +- [ ] Context isolation or skill composition is needed +- [ ] Clear role/persona emerges +- [ ] `model` selection is deliberate (not just `inherit`) +- [ ] `skills` list is right-sized (not too many) +- [ ] File at `agents/<name>/AGENT.md` -- 2.49.1