refactor: migrate commands to user-invocable skills
Claude Code has unified commands into skills with the user-invocable frontmatter field. This migration: - Converts 20 commands to skills with user-invocable: true - Consolidates docs into single writing-capabilities.md - Rewrites capability-writing skill for unified model - Updates CLAUDE.md, Makefile, and other references - Removes commands/ directory Skills now have two types: - user-invocable: true - workflows users trigger with /name - user-invocable: false - background knowledge auto-loaded Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
508
docs/writing-capabilities.md
Normal file
508
docs/writing-capabilities.md
Normal file
@@ -0,0 +1,508 @@
|
||||
# Writing Capabilities
|
||||
|
||||
A comprehensive guide to creating capabilities for the Claude Code AI workflow system.
|
||||
|
||||
> **Official Documentation**: For the most up-to-date Claude Code documentation, see https://code.claude.com/docs
|
||||
|
||||
## Component Types
|
||||
|
||||
The architecture repository uses two component types:
|
||||
|
||||
| Component | Location | Purpose | Invocation |
|
||||
|-----------|----------|---------|------------|
|
||||
| **Skill** | `skills/<name>/SKILL.md` | Knowledge modules and workflows | Auto-triggered or `/skill-name` |
|
||||
| **Agent** | `agents/<name>/AGENT.md` | Isolated subtask handlers | Spawned via Task tool |
|
||||
|
||||
### Skills: Two Types
|
||||
|
||||
Skills come in two flavors based on the `user-invocable` frontmatter field:
|
||||
|
||||
| Type | `user-invocable` | Purpose | Example |
|
||||
|------|------------------|---------|---------|
|
||||
| **User-invocable** | `true` | Workflows users trigger with `/skill-name` | `/work-issue`, `/dashboard` |
|
||||
| **Background** | `false` | Reference knowledge auto-loaded when needed | `gitea`, `issue-writing` |
|
||||
|
||||
User-invocable skills replaced the former "commands" - they define workflows that users trigger directly.
|
||||
|
||||
### Agents: Isolated Workers
|
||||
|
||||
Agents are specialized subprocesses that:
|
||||
- Combine multiple skills into focused personas
|
||||
- Run with isolated context (don't pollute main conversation)
|
||||
- Handle complex subtasks autonomously
|
||||
- Can run in parallel or background
|
||||
|
||||
---
|
||||
|
||||
## Writing Skills
|
||||
|
||||
Skills are markdown files in the `skills/` directory, each in its own folder.
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
├── gitea/ # Background skill
|
||||
│ └── SKILL.md
|
||||
├── work-issue/ # User-invocable skill
|
||||
│ └── SKILL.md
|
||||
└── issue-writing/ # Background skill
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
Every skill requires YAML frontmatter starting on line 1:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill does and when to use it.
|
||||
Include trigger terms for auto-detection.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
argument-hint: <required-arg> [optional-arg]
|
||||
---
|
||||
```
|
||||
|
||||
#### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Lowercase, hyphens only (max 64 chars). Must match directory name. |
|
||||
| `description` | What the skill does + when to use (max 1024 chars). Critical for triggering. |
|
||||
|
||||
#### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `user-invocable` | Whether skill appears in `/` menu. Default: `true` |
|
||||
| `model` | Model to use: `haiku`, `sonnet`, `opus` |
|
||||
| `argument-hint` | For user-invocable: `<required>`, `[optional]` |
|
||||
| `context` | Use `fork` for isolated context |
|
||||
| `allowed-tools` | Restrict available tools (YAML list) |
|
||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks |
|
||||
|
||||
### User-Invocable Skills (Workflows)
|
||||
|
||||
These replace the former "commands" - workflows users invoke with `/skill-name`.
|
||||
|
||||
**Example: `/work-issue`**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: work-issue
|
||||
description: >
|
||||
Work on a Gitea issue. Fetches issue details and sets up branch.
|
||||
Use when working on issues, implementing features, or when user says /work-issue.
|
||||
model: haiku
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
1. **View the issue** with `--comments` flag
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<short-title>`
|
||||
3. **Plan**: Use TodoWrite to break down work
|
||||
4. **Implement** following architectural patterns
|
||||
5. **Commit** with message referencing the issue
|
||||
6. **Push** and **Create PR**
|
||||
```
|
||||
|
||||
**Key patterns for user-invocable skills:**
|
||||
|
||||
1. **Argument handling**: Use `$1`, `$2` for positional arguments
|
||||
2. **Skill references**: Use `@~/.claude/skills/name/SKILL.md` to include background skills
|
||||
3. **Approval workflows**: Ask before significant actions
|
||||
4. **Clear steps**: Numbered, actionable workflow steps
|
||||
|
||||
### Background Skills (Reference)
|
||||
|
||||
Knowledge modules that Claude applies automatically when context matches.
|
||||
|
||||
**Example: `gitea`**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: gitea
|
||||
description: >
|
||||
View, create, and manage Gitea issues and pull requests using tea CLI.
|
||||
Use when working with issues, PRs, or when user mentions tea, gitea.
|
||||
model: haiku
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Gitea CLI (tea)
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Issues
|
||||
```bash
|
||||
tea issues # List open issues
|
||||
tea issues <number> # View issue details
|
||||
tea issues create --title "..." --description "..."
|
||||
```
|
||||
...
|
||||
```
|
||||
|
||||
**Key patterns for background skills:**
|
||||
|
||||
1. **Rich descriptions**: Include trigger terms like tool names, actions
|
||||
2. **Reference material**: Commands, templates, patterns, checklists
|
||||
3. **No workflow steps**: Just knowledge, not actions
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
The `description` field determines when Claude applies the skill. Include:
|
||||
|
||||
1. **What the skill does**: Specific capabilities
|
||||
2. **When to use it**: Trigger terms users would mention
|
||||
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: >
|
||||
View, create, and manage Gitea issues and pull requests using tea CLI.
|
||||
Use when working with issues, PRs, viewing issue details, creating pull
|
||||
requests, or when the user mentions tea, gitea, or issue numbers.
|
||||
```
|
||||
|
||||
### Argument Handling (User-Invocable Skills)
|
||||
|
||||
User-invocable skills can accept arguments via `$1`, `$2`, etc.
|
||||
|
||||
**Argument hints:**
|
||||
- `<arg>` - Required argument
|
||||
- `[arg]` - Optional argument
|
||||
- `<arg1> [arg2]` - Mix of both
|
||||
|
||||
**Example with optional argument:**
|
||||
```yaml
|
||||
---
|
||||
name: groom
|
||||
argument-hint: [issue-number]
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
## If issue number provided ($1):
|
||||
1. Fetch that specific issue
|
||||
2. Evaluate against checklist
|
||||
...
|
||||
|
||||
## If no argument:
|
||||
1. List all open issues
|
||||
2. Review each against checklist
|
||||
...
|
||||
```
|
||||
|
||||
### Skill References
|
||||
|
||||
User-invocable skills include background skills using file references:
|
||||
|
||||
```markdown
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
```
|
||||
|
||||
**Important**: Do NOT use phrases like "Use the gitea skill" - skills have ~20% auto-activation rate. File references guarantee the content is loaded.
|
||||
|
||||
### Approval Workflows
|
||||
|
||||
User-invocable skills should ask for approval before significant actions:
|
||||
|
||||
```markdown
|
||||
4. **Present plan** for approval
|
||||
5. **If approved**, create the issues
|
||||
6. **Present summary** with links
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Agents
|
||||
|
||||
Agents are specialized subprocesses that combine skills for complex, isolated tasks.
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
agents/
|
||||
└── code-reviewer/
|
||||
└── AGENT.md
|
||||
```
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Review code for quality, bugs, and style issues
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
```
|
||||
|
||||
#### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Agent identifier (lowercase, hyphens). Match directory name. |
|
||||
| `description` | What the agent does. Used for matching when spawning. |
|
||||
|
||||
#### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `model` | `haiku`, `sonnet`, `opus`, or `inherit` |
|
||||
| `skills` | Comma-separated skill names the agent can access |
|
||||
| `disallowedTools` | Block specific tools (e.g., Edit, Write for read-only) |
|
||||
| `permissionMode` | `default` or `bypassPermissions` |
|
||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks |
|
||||
|
||||
### Agent Document Structure
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
Brief description of the agent's role.
|
||||
|
||||
## Skills
|
||||
- skill1
|
||||
- skill2
|
||||
|
||||
## Capabilities
|
||||
What the agent can do.
|
||||
|
||||
## When to Use
|
||||
Guidance on when to spawn this agent.
|
||||
|
||||
## Behavior
|
||||
Operational rules and constraints.
|
||||
```
|
||||
|
||||
### Built-in Agents
|
||||
|
||||
Claude Code provides built-in agents - prefer these before creating custom ones:
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| **Explore** | Codebase exploration, finding files, searching code |
|
||||
| **Plan** | Implementation planning, architectural decisions |
|
||||
|
||||
### Skill Composition
|
||||
|
||||
Agents gain expertise by combining skills:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Code Reviewer Agent │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────────┐ │
|
||||
│ │ gitea │ │ code-review │ │
|
||||
│ │ CLI │ │ patterns │ │
|
||||
│ └─────────┘ └─────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Use Cases for Agents
|
||||
|
||||
1. **Parallel processing**: Spawn multiple agents for independent tasks
|
||||
2. **Context isolation**: Deep exploration without polluting main context
|
||||
3. **Complex workflows**: Iterative decision-making with multiple skills
|
||||
4. **Background execution**: Long-running tasks while user continues working
|
||||
|
||||
### Model Selection
|
||||
|
||||
| Model | Best For |
|
||||
|-------|----------|
|
||||
| `haiku` | Simple tasks, formatting, batch processing |
|
||||
| `sonnet` | Most agent tasks, code review (default choice) |
|
||||
| `opus` | Complex analysis, security audits, architectural decisions |
|
||||
|
||||
---
|
||||
|
||||
## Decision Guide
|
||||
|
||||
### When to Create a User-Invocable Skill
|
||||
|
||||
Create when you have:
|
||||
- Repeatable workflow used multiple times
|
||||
- User explicitly triggers the action
|
||||
- Clear start and end points
|
||||
- Approval checkpoints needed
|
||||
|
||||
### When to Create a Background Skill
|
||||
|
||||
Create when:
|
||||
- You explain the same concepts repeatedly
|
||||
- Multiple user-invocable skills need the same knowledge
|
||||
- Quality is inconsistent without explicit guidance
|
||||
- There's a clear domain that doesn't fit existing skills
|
||||
|
||||
### When to Create an Agent
|
||||
|
||||
Create when:
|
||||
- Multiple skills needed together for complex tasks
|
||||
- Context isolation required
|
||||
- Parallel execution possible
|
||||
- Autonomous exploration needed
|
||||
- Specialist persona improves outputs
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Scenario | Component | Reason |
|
||||
|----------|-----------|--------|
|
||||
| User types `/work-issue 42` | User-invocable skill | Explicit user trigger |
|
||||
| Need tea CLI reference | Background skill | Auto-loaded knowledge |
|
||||
| Review 20 issues in parallel | Agent | Batch processing, isolation |
|
||||
| Create one issue | User-invocable skill | Single workflow |
|
||||
| Deep architectural analysis | Agent | Complex, isolated work |
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
### User-Invocable Skill Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill does and when to use it.
|
||||
Use when [trigger conditions] or when user says /skill-name.
|
||||
model: haiku
|
||||
argument-hint: <required> [optional]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
@~/.claude/skills/relevant-skill/SKILL.md
|
||||
|
||||
Brief intro if needed.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### Background Skill Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill teaches and when to use it.
|
||||
Include trigger conditions in description.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Brief description of what this skill covers.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
Explain fundamental ideas.
|
||||
|
||||
## Patterns and Templates
|
||||
|
||||
Provide reusable structures.
|
||||
|
||||
## Guidelines
|
||||
|
||||
List rules and best practices.
|
||||
|
||||
## Examples
|
||||
|
||||
Show concrete illustrations.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
Document pitfalls to avoid.
|
||||
```
|
||||
|
||||
### Agent Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name
|
||||
description: What this agent does and when to spawn it
|
||||
model: sonnet
|
||||
skills: skill1, skill2
|
||||
---
|
||||
|
||||
You are a [role] specialist that [primary function].
|
||||
|
||||
## When Invoked
|
||||
|
||||
1. **Gather context**: What 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklists
|
||||
|
||||
### Before Creating a User-Invocable Skill
|
||||
|
||||
- [ ] Workflow is repeatable (used multiple times)
|
||||
- [ ] User explicitly triggers it
|
||||
- [ ] File at `skills/<name>/SKILL.md`
|
||||
- [ ] `user-invocable: true` in frontmatter
|
||||
- [ ] `description` includes "Use when... or when user says /skill-name"
|
||||
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
||||
- [ ] Approval checkpoints before significant actions
|
||||
- [ ] Clear numbered workflow steps
|
||||
|
||||
### Before Creating a Background Skill
|
||||
|
||||
- [ ] Knowledge used in multiple places
|
||||
- [ ] Doesn't fit existing skills
|
||||
- [ ] File at `skills/<name>/SKILL.md`
|
||||
- [ ] `user-invocable: false` in frontmatter
|
||||
- [ ] `description` includes trigger terms
|
||||
- [ ] Content is specific and actionable
|
||||
|
||||
### Before Creating an Agent
|
||||
|
||||
- [ ] Built-in agents (Explore, Plan) aren't sufficient
|
||||
- [ ] Context isolation or skill composition needed
|
||||
- [ ] File at `agents/<name>/AGENT.md`
|
||||
- [ ] `model` selection is deliberate
|
||||
- [ ] `skills` list is right-sized
|
||||
- [ ] Clear role/persona emerges
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How components fit together
|
||||
- [skills/capability-writing/SKILL.md](../skills/capability-writing/SKILL.md): Quick reference
|
||||
Reference in New Issue
Block a user