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 <noreply@anthropic.com>
This commit was merged in pull request #77.
This commit is contained in:
424
skills/capability-writing/SKILL.md
Normal file
424
skills/capability-writing/SKILL.md
Normal file
@@ -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/<name>/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/<name>.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: What this command does (one-line summary)
|
||||
argument-hint: <required> [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: `<required>`, `[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/<name>/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-<title>`
|
||||
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`
|
||||
Reference in New Issue
Block a user