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:
46
CLAUDE.md
46
CLAUDE.md
@@ -18,8 +18,7 @@ make install
|
|||||||
| `manifesto.md` | Organization vision, personas, beliefs, principles |
|
| `manifesto.md` | Organization vision, personas, beliefs, principles |
|
||||||
| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
|
| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
|
||||||
| `learnings/` | Historical record and governance |
|
| `learnings/` | Historical record and governance |
|
||||||
| `commands/` | AI workflow entry points (/work-issue, /manifesto, etc.) |
|
| `skills/` | AI workflows and knowledge modules |
|
||||||
| `skills/` | Tool and practice knowledge |
|
|
||||||
| `agents/` | Focused subtask handlers |
|
| `agents/` | Focused subtask handlers |
|
||||||
| `settings.json` | Claude Code configuration |
|
| `settings.json` | Claude Code configuration |
|
||||||
| `Makefile` | Install symlinks to ~/.claude/ |
|
| `Makefile` | Install symlinks to ~/.claude/ |
|
||||||
@@ -31,29 +30,28 @@ architecture/
|
|||||||
├── manifesto.md # Organization vision and beliefs
|
├── manifesto.md # Organization vision and beliefs
|
||||||
├── software-architecture.md # Patterns linked to beliefs (DDD, ES)
|
├── software-architecture.md # Patterns linked to beliefs (DDD, ES)
|
||||||
├── learnings/ # Captured learnings and governance
|
├── learnings/ # Captured learnings and governance
|
||||||
├── commands/ # Slash commands (/work-issue, /dashboard)
|
├── skills/ # User-invocable (/work-issue) and background skills
|
||||||
├── skills/ # Knowledge modules (auto-triggered)
|
├── agents/ # Focused subtask handlers (isolated context)
|
||||||
├── agents/ # Focused subtask handlers (isolated context)
|
├── scripts/ # Hook scripts (pre-commit, token loading)
|
||||||
├── scripts/ # Hook scripts (pre-commit, token loading)
|
├── settings.json # Claude Code settings
|
||||||
├── settings.json # Claude Code settings
|
└── Makefile # Install/uninstall symlinks
|
||||||
└── Makefile # Install/uninstall symlinks
|
|
||||||
```
|
```
|
||||||
|
|
||||||
All files symlink to `~/.claude/` via `make install`.
|
All files symlink to `~/.claude/` via `make install`.
|
||||||
|
|
||||||
## Two Levels of Vision
|
## Two Levels of Vision
|
||||||
|
|
||||||
| Level | Document | Command | Purpose |
|
| Level | Document | Skill | Purpose |
|
||||||
|-------|----------|---------|---------|
|
|-------|----------|-------|---------|
|
||||||
| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
|
| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
|
||||||
| Product | `vision.md` | `/vision` | Product-specific direction and goals |
|
| Product | `vision.md` | `/vision` | Product-specific direction and goals |
|
||||||
|
|
||||||
See the manifesto for our identity, personas, and beliefs about AI-augmented development.
|
See the manifesto for our identity, personas, and beliefs about AI-augmented development.
|
||||||
|
|
||||||
## Available Commands
|
## Available Skills
|
||||||
|
|
||||||
| Command | Description |
|
| Skill | Description |
|
||||||
|---------|-------------|
|
|-------|-------------|
|
||||||
| `/manifesto` | View/manage organization manifesto |
|
| `/manifesto` | View/manage organization manifesto |
|
||||||
| `/vision` | View/manage product vision and milestones |
|
| `/vision` | View/manage product vision and milestones |
|
||||||
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
|
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
|
||||||
@@ -79,28 +77,28 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
|
|||||||
## Architecture Components
|
## Architecture Components
|
||||||
|
|
||||||
### Skills
|
### Skills
|
||||||
Knowledge modules that teach Claude how to do something.
|
|
||||||
|
|
||||||
|
Skills come in two types:
|
||||||
|
|
||||||
|
**User-invocable** (`user-invocable: true`): Workflows users trigger with `/skill-name`
|
||||||
|
- **Purpose**: Orchestrate workflows with user interaction
|
||||||
|
- **Location**: `skills/<name>/SKILL.md`
|
||||||
|
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
|
||||||
|
|
||||||
|
**Background** (`user-invocable: false`): Knowledge auto-loaded when needed
|
||||||
- **Purpose**: Encode best practices and tool knowledge
|
- **Purpose**: Encode best practices and tool knowledge
|
||||||
- **Location**: `skills/<name>/SKILL.md`
|
- **Location**: `skills/<name>/SKILL.md`
|
||||||
- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
|
- **Usage**: Referenced by other skills via `@~/.claude/skills/xxx/SKILL.md`
|
||||||
|
|
||||||
### Commands
|
|
||||||
User-facing entry points invoked with `/command-name`.
|
|
||||||
|
|
||||||
- **Purpose**: Orchestrate workflows with user interaction
|
|
||||||
- **Location**: `commands/<name>.md`
|
|
||||||
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
|
|
||||||
|
|
||||||
### Agents
|
### Agents
|
||||||
Focused units that handle specific subtasks in isolated context.
|
Focused units that handle specific subtasks in isolated context.
|
||||||
|
|
||||||
- **Purpose**: Complex subtasks that benefit from isolation
|
- **Purpose**: Complex subtasks that benefit from isolation
|
||||||
- **Location**: `agents/<name>/agent.md`
|
- **Location**: `agents/<name>/AGENT.md`
|
||||||
- **Usage**: Spawned via Task tool, return results to caller
|
- **Usage**: Spawned via Task tool, return results to caller
|
||||||
|
|
||||||
### Learnings
|
### Learnings
|
||||||
Captured insights from work, encoded into skills/commands/agents.
|
Captured insights from work, encoded into skills/agents.
|
||||||
|
|
||||||
- **Purpose**: Historical record + governance + continuous improvement
|
- **Purpose**: Historical record + governance + continuous improvement
|
||||||
- **Location**: `learnings/YYYY-MM-DD-title.md`
|
- **Location**: `learnings/YYYY-MM-DD-title.md`
|
||||||
|
|||||||
2
Makefile
2
Makefile
@@ -4,7 +4,7 @@ CLAUDE_DIR := $(HOME)/.claude
|
|||||||
REPO_DIR := $(shell pwd)
|
REPO_DIR := $(shell pwd)
|
||||||
|
|
||||||
# Items to symlink
|
# Items to symlink
|
||||||
ITEMS := commands scripts skills agents settings.json
|
ITEMS := scripts skills agents settings.json
|
||||||
|
|
||||||
install:
|
install:
|
||||||
@echo "Installing Claude Code config symlinks..."
|
@echo "Installing Claude Code config symlinks..."
|
||||||
|
|||||||
@@ -1,709 +0,0 @@
|
|||||||
# Writing Agents
|
|
||||||
|
|
||||||
A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.
|
|
||||||
|
|
||||||
## What is an Agent?
|
|
||||||
|
|
||||||
Agents are **specialized subprocesses** that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.
|
|
||||||
|
|
||||||
Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Agents live in the `agents/` directory, each in its own folder:
|
|
||||||
|
|
||||||
```
|
|
||||||
agents/
|
|
||||||
└── product-manager/
|
|
||||||
└── AGENT.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why AGENT.md?
|
|
||||||
|
|
||||||
The uppercase `AGENT.md` filename:
|
|
||||||
- Makes the agent file immediately visible in directory listings
|
|
||||||
- Follows a consistent convention across all agents
|
|
||||||
- Clearly identifies the primary file in an agent folder
|
|
||||||
|
|
||||||
### Supporting Files (Optional)
|
|
||||||
|
|
||||||
An agent folder can contain additional files if needed:
|
|
||||||
|
|
||||||
```
|
|
||||||
agents/
|
|
||||||
└── code-reviewer/
|
|
||||||
├── AGENT.md # Main agent document (required)
|
|
||||||
└── checklists/ # Supporting materials
|
|
||||||
└── security.md
|
|
||||||
```
|
|
||||||
|
|
||||||
However, prefer keeping everything in `AGENT.md` when possible—agent definitions should be concise.
|
|
||||||
|
|
||||||
## Agent Document Structure
|
|
||||||
|
|
||||||
A well-structured `AGENT.md` follows this pattern:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Agent Name
|
|
||||||
|
|
||||||
Brief description of what this agent does.
|
|
||||||
|
|
||||||
## Skills
|
|
||||||
List of skills this agent has access to.
|
|
||||||
|
|
||||||
## Capabilities
|
|
||||||
What the agent can do—its areas of competence.
|
|
||||||
|
|
||||||
## When to Use
|
|
||||||
Guidance on when to spawn this agent.
|
|
||||||
|
|
||||||
## Behavior
|
|
||||||
How the agent should operate—rules and constraints.
|
|
||||||
```
|
|
||||||
|
|
||||||
All sections are important:
|
|
||||||
- **Skills**: Defines what knowledge the agent has
|
|
||||||
- **Capabilities**: Tells spawners what to expect
|
|
||||||
- **When to Use**: Prevents misuse and guides selection
|
|
||||||
- **Behavior**: Sets expectations for operation
|
|
||||||
|
|
||||||
## YAML Frontmatter
|
|
||||||
|
|
||||||
Agent files support YAML frontmatter for configuration. While the body content defines the agent's personality and instructions, frontmatter controls its technical behavior.
|
|
||||||
|
|
||||||
### Required Fields
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| `name` | Agent identifier (lowercase, hyphens). Should match directory name. |
|
|
||||||
| `description` | What the agent does. Used for matching when spawning agents. |
|
|
||||||
|
|
||||||
### Optional Fields
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| `model` | Model to use: `haiku`, `sonnet`, `opus`, or `inherit` (default). |
|
|
||||||
| `skills` | Comma-separated list of skills the agent can access. |
|
|
||||||
| `disallowedTools` | Explicitly block specific tools from this agent. |
|
|
||||||
| `permissionMode` | Permission behavior: `default`, `bypassPermissions`, or custom. |
|
|
||||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this agent. |
|
|
||||||
|
|
||||||
### Example Frontmatter
|
|
||||||
|
|
||||||
**Basic agent:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: code-reviewer
|
|
||||||
description: Review code for quality, bugs, and style issues.
|
|
||||||
model: sonnet
|
|
||||||
skills: gitea, code-review
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Agent with tool restrictions:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: read-only-analyst
|
|
||||||
description: Analyze code without making changes.
|
|
||||||
model: haiku
|
|
||||||
skills: code-review
|
|
||||||
disallowedTools:
|
|
||||||
- Edit
|
|
||||||
- Write
|
|
||||||
- Bash
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Agent with hooks:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: database-admin
|
|
||||||
description: Manage database operations safely.
|
|
||||||
model: opus
|
|
||||||
hooks:
|
|
||||||
- type: PreToolUse
|
|
||||||
matcher: Bash
|
|
||||||
command: echo "Validating database command..."
|
|
||||||
- type: Stop
|
|
||||||
command: echo "Database operation completed"
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### Permission Modes
|
|
||||||
|
|
||||||
The `permissionMode` field controls how the agent handles tool permissions:
|
|
||||||
|
|
||||||
| Mode | Behavior |
|
|
||||||
|------|----------|
|
|
||||||
| `default` | Inherits parent's permission settings (standard behavior) |
|
|
||||||
| `bypassPermissions` | Skip permission prompts (use for trusted, well-tested agents) |
|
|
||||||
|
|
||||||
Use `bypassPermissions` sparingly—only for agents that are thoroughly tested and operate within safe boundaries.
|
|
||||||
|
|
||||||
## Built-in Agents
|
|
||||||
|
|
||||||
Claude Code provides built-in agents that you can leverage instead of creating custom ones:
|
|
||||||
|
|
||||||
| Agent | Purpose | When to Use |
|
|
||||||
|-------|---------|-------------|
|
|
||||||
| **Explore** | Codebase exploration and search | Finding files, understanding structure, searching code. Powered by Haiku for efficiency. |
|
|
||||||
| **Plan** | Implementation planning | Designing approaches, breaking down tasks, architectural decisions. |
|
|
||||||
|
|
||||||
Consider using built-in agents before creating custom ones—they're optimized for common tasks.
|
|
||||||
|
|
||||||
## How Agents Combine Skills
|
|
||||||
|
|
||||||
Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
|
|
||||||
|
|
||||||
### Skill Composition
|
|
||||||
|
|
||||||
```
|
|
||||||
┌────────────────────────────────────────────────┐
|
|
||||||
│ Product Manager Agent │
|
|
||||||
│ │
|
|
||||||
│ ┌──────────┐ ┌──────────────┐ │
|
|
||||||
│ │ gitea │ │issue-writing │ │
|
|
||||||
│ │ │ │ │ │
|
|
||||||
│ │ CLI │ │ Structure │ │
|
|
||||||
│ │ commands │ │ patterns │ │
|
|
||||||
│ └──────────┘ └──────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ ┌──────────────────┐ ┌─────────────────┐ │
|
|
||||||
│ │backlog-grooming │ │roadmap-planning │ │
|
|
||||||
│ │ │ │ │ │
|
|
||||||
│ │ Review │ │ Feature │ │
|
|
||||||
│ │ checklists │ │ breakdown │ │
|
|
||||||
│ └──────────────────┘ └─────────────────┘ │
|
|
||||||
│ │
|
|
||||||
└────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
The agent can:
|
|
||||||
- Use **gitea** to interact with issues and PRs
|
|
||||||
- Apply **issue-writing** patterns when creating content
|
|
||||||
- Follow **backlog-grooming** checklists when reviewing
|
|
||||||
- Use **roadmap-planning** strategies when breaking down features
|
|
||||||
|
|
||||||
### Emergent Capabilities
|
|
||||||
|
|
||||||
When skills combine, new capabilities emerge:
|
|
||||||
|
|
||||||
| Skills Combined | Emergent Capability |
|
|
||||||
|-----------------|---------------------|
|
|
||||||
| gitea + issue-writing | Create well-structured issues programmatically |
|
|
||||||
| backlog-grooming + issue-writing | Improve existing issues systematically |
|
|
||||||
| roadmap-planning + gitea | Plan and create linked issue hierarchies |
|
|
||||||
| All four skills | Full backlog management lifecycle |
|
|
||||||
|
|
||||||
## Use Cases for Agents
|
|
||||||
|
|
||||||
### 1. Parallel Processing
|
|
||||||
|
|
||||||
Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.
|
|
||||||
|
|
||||||
```
|
|
||||||
Command: /groom (batch mode)
|
|
||||||
│
|
|
||||||
├─── Spawn Agent: Review issues #1-5
|
|
||||||
│
|
|
||||||
├─── Spawn Agent: Review issues #6-10
|
|
||||||
│
|
|
||||||
└─── Spawn Agent: Review issues #11-15
|
|
||||||
|
|
||||||
↓ (agents work in parallel)
|
|
||||||
|
|
||||||
Results aggregated by command
|
|
||||||
```
|
|
||||||
|
|
||||||
**Use when:**
|
|
||||||
- Tasks are independent and don't need to share state
|
|
||||||
- Workload can be divided into discrete chunks
|
|
||||||
- Speed matters more than sequential consistency
|
|
||||||
|
|
||||||
### 2. Context Isolation
|
|
||||||
|
|
||||||
Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.
|
|
||||||
|
|
||||||
```
|
|
||||||
Main Context Agent Context
|
|
||||||
┌─────────────────┐ ┌─────────────────┐
|
|
||||||
│ User working on │ │ Isolated work │
|
|
||||||
│ feature X │ spawn │ on backlog │
|
|
||||||
│ │ ─────────► │ review │
|
|
||||||
│ (preserves │ │ │
|
|
||||||
│ feature X │ return │ (doesn't know │
|
|
||||||
│ context) │ ◄───────── │ about X) │
|
|
||||||
└─────────────────┘ └─────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**Use when:**
|
|
||||||
- Subtask requires deep exploration that would pollute main context
|
|
||||||
- Work involves many files or concepts unrelated to main task
|
|
||||||
- You want clean separation between different concerns
|
|
||||||
|
|
||||||
### 3. Complex Workflows
|
|
||||||
|
|
||||||
Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.
|
|
||||||
|
|
||||||
```
|
|
||||||
Command: /plan-issues "add user authentication"
|
|
||||||
│
|
|
||||||
└─── Spawn product-manager agent
|
|
||||||
│
|
|
||||||
├── Explore codebase to understand structure
|
|
||||||
├── Research authentication patterns
|
|
||||||
├── Design issue breakdown
|
|
||||||
├── Create issues in dependency order
|
|
||||||
└── Return summary to command
|
|
||||||
```
|
|
||||||
|
|
||||||
**Use when:**
|
|
||||||
- Task requires iterative decision-making
|
|
||||||
- Workflow has many steps that depend on intermediate results
|
|
||||||
- Specialist expertise (via combined skills) adds value
|
|
||||||
|
|
||||||
### 4. Autonomous Exploration
|
|
||||||
|
|
||||||
Agents can explore codebases independently, building understanding without polluting the main conversation.
|
|
||||||
|
|
||||||
**Use when:**
|
|
||||||
- You need to understand a new part of the codebase
|
|
||||||
- Exploration might involve many file reads and searches
|
|
||||||
- Results should be summarized, not shown in full
|
|
||||||
|
|
||||||
### 5. Background Execution
|
|
||||||
|
|
||||||
Agents can run in the background while you continue working. Background agents execute asynchronously and notify the main thread when complete.
|
|
||||||
|
|
||||||
```
|
|
||||||
User working Background Agent
|
|
||||||
┌─────────────────┐ ┌─────────────────┐
|
|
||||||
│ Continue coding │ │ Running tests │
|
|
||||||
│ on feature │ │ in background │
|
|
||||||
│ │ │ │
|
|
||||||
│ (not blocked) │ notify │ (async work) │
|
|
||||||
│ │ ◄───────── │ │
|
|
||||||
└─────────────────┘ └─────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**Use when:**
|
|
||||||
- Task is long-running (test suites, large codebase analysis)
|
|
||||||
- You want to continue working while the agent operates
|
|
||||||
- Results are needed later, not immediately
|
|
||||||
|
|
||||||
Background agents can send messages to wake up the main agent when they have results or need attention.
|
|
||||||
|
|
||||||
## When to Use an Agent vs Direct Skill Invocation
|
|
||||||
|
|
||||||
### Use Direct Skill Invocation When:
|
|
||||||
|
|
||||||
- **Simple, single-skill task**: Writing one issue doesn't need an agent
|
|
||||||
- **Main context is relevant**: The current conversation context helps
|
|
||||||
- **Quick reference needed**: Just need to check a pattern or command
|
|
||||||
- **Sequential workflow**: Command can orchestrate step-by-step
|
|
||||||
|
|
||||||
Example: Creating a single issue with `/create-issue`
|
|
||||||
```
|
|
||||||
Command reads issue-writing skill directly
|
|
||||||
│
|
|
||||||
└── Creates one issue following patterns
|
|
||||||
```
|
|
||||||
|
|
||||||
### Use an Agent When:
|
|
||||||
|
|
||||||
- **Multiple skills needed together**: Complex tasks benefit from composition
|
|
||||||
- **Context isolation required**: Don't want to pollute main conversation
|
|
||||||
- **Parallel execution possible**: Can divide and conquer
|
|
||||||
- **Autonomous exploration needed**: Agent can figure things out independently
|
|
||||||
- **Specialist persona helps**: "Product manager" framing improves outputs
|
|
||||||
|
|
||||||
Example: Grooming entire backlog with `/groom`
|
|
||||||
```
|
|
||||||
Command spawns product-manager agent
|
|
||||||
│
|
|
||||||
└── Agent iterates through all issues
|
|
||||||
using multiple skills
|
|
||||||
```
|
|
||||||
|
|
||||||
### Decision Matrix
|
|
||||||
|
|
||||||
| Scenario | Agent? | Reason |
|
|
||||||
|----------|--------|--------|
|
|
||||||
| Create one issue | No | Single skill, simple task |
|
|
||||||
| Review 20 issues | Yes | Batch processing, isolation |
|
|
||||||
| Quick CLI lookup | No | Just need gitea reference |
|
|
||||||
| Plan new feature | Yes | Multiple skills, exploration |
|
|
||||||
| Fix issue title | No | Trivial edit |
|
|
||||||
| Reorganize backlog | Yes | Complex, multi-skill workflow |
|
|
||||||
|
|
||||||
## Annotated Example: Product Manager Agent
|
|
||||||
|
|
||||||
Let's examine the `product-manager` agent in detail:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Product Manager Agent
|
|
||||||
|
|
||||||
Specialized agent for backlog management and roadmap planning.
|
|
||||||
```
|
|
||||||
|
|
||||||
**The opening** identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Skills
|
|
||||||
|
|
||||||
- gitea
|
|
||||||
- issue-writing
|
|
||||||
- backlog-grooming
|
|
||||||
- roadmap-planning
|
|
||||||
```
|
|
||||||
|
|
||||||
**Skills section** lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:
|
|
||||||
- Reading/writing issues (gitea)
|
|
||||||
- Creating quality content (issue-writing)
|
|
||||||
- Evaluating existing issues (backlog-grooming)
|
|
||||||
- Planning work strategically (roadmap-planning)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Capabilities
|
|
||||||
|
|
||||||
This agent can:
|
|
||||||
- Review and improve existing issues
|
|
||||||
- Create new well-structured issues
|
|
||||||
- Analyze the backlog for gaps and priorities
|
|
||||||
- Plan feature breakdowns
|
|
||||||
- Maintain roadmap clarity
|
|
||||||
```
|
|
||||||
|
|
||||||
**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
|
|
||||||
- "Review and improve" = backlog-grooming + issue-writing
|
|
||||||
- "Create new issues" = gitea + issue-writing
|
|
||||||
- "Analyze backlog" = backlog-grooming + roadmap-planning
|
|
||||||
- "Plan breakdowns" = roadmap-planning + issue-writing
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## When to Use
|
|
||||||
|
|
||||||
Spawn this agent for:
|
|
||||||
- Batch operations on multiple issues
|
|
||||||
- Comprehensive backlog reviews
|
|
||||||
- Feature planning that requires codebase exploration
|
|
||||||
- Complex issue creation with dependencies
|
|
||||||
```
|
|
||||||
|
|
||||||
**When to Use section** guides appropriate usage. Note the criteria:
|
|
||||||
- "Batch operations" → Parallel/isolation benefit
|
|
||||||
- "Comprehensive reviews" → Complex workflow benefit
|
|
||||||
- "Requires exploration" → Context isolation benefit
|
|
||||||
- "Complex with dependencies" → Multi-skill benefit
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Behavior
|
|
||||||
|
|
||||||
- Always fetches current issue state before making changes
|
|
||||||
- Asks for approval before creating or modifying issues
|
|
||||||
- Provides clear summaries of actions taken
|
|
||||||
- Uses the tea CLI for all Forgejo operations
|
|
||||||
```
|
|
||||||
|
|
||||||
**Behavior section** sets operational rules. These ensure:
|
|
||||||
- Accuracy: Fetches current state, doesn't assume
|
|
||||||
- Safety: Asks before acting
|
|
||||||
- Transparency: Summarizes what happened
|
|
||||||
- Consistency: Uses standard tooling
|
|
||||||
|
|
||||||
## Naming Conventions
|
|
||||||
|
|
||||||
### Agent Folder Names
|
|
||||||
|
|
||||||
- Use **kebab-case**: `product-manager`, `code-reviewer`
|
|
||||||
- Name by **role or persona**: what the agent "is"
|
|
||||||
- Keep **recognizable**: familiar roles are easier to understand
|
|
||||||
|
|
||||||
Good names:
|
|
||||||
- `product-manager` - Recognizable role
|
|
||||||
- `code-reviewer` - Clear function
|
|
||||||
- `security-auditor` - Specific expertise
|
|
||||||
- `documentation-writer` - Focused purpose
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- `helper` - Too vague
|
|
||||||
- `do-stuff` - Not a role
|
|
||||||
- `issue-thing` - Not recognizable
|
|
||||||
|
|
||||||
### Agent Titles
|
|
||||||
|
|
||||||
The H1 title in `AGENT.md` should be the role name in Title Case:
|
|
||||||
|
|
||||||
| Folder | Title |
|
|
||||||
|--------|-------|
|
|
||||||
| `product-manager` | Product Manager Agent |
|
|
||||||
| `code-reviewer` | Code Reviewer Agent |
|
|
||||||
| `security-auditor` | Security Auditor Agent |
|
|
||||||
|
|
||||||
## Model Selection
|
|
||||||
|
|
||||||
Agents can specify which Claude model to use via the `model` field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.
|
|
||||||
|
|
||||||
### Available Models
|
|
||||||
|
|
||||||
| Model | Characteristics | Best For |
|
|
||||||
|-------|-----------------|----------|
|
|
||||||
| `haiku` | Fastest, most cost-effective | Simple structured tasks, formatting, basic transformations |
|
|
||||||
| `sonnet` | Balanced speed and capability | Most agent tasks, code review, issue management |
|
|
||||||
| `opus` | Most capable, best reasoning | Complex analysis, architectural decisions, nuanced judgment |
|
|
||||||
| `inherit` | Uses parent context's model | When agent should match caller's capability level |
|
|
||||||
|
|
||||||
### Decision Matrix
|
|
||||||
|
|
||||||
| Agent Task Type | Recommended Model | Reasoning |
|
|
||||||
|-----------------|-------------------|-----------|
|
|
||||||
| Structured output formatting | `haiku` | Pattern-following, no complex reasoning |
|
|
||||||
| Code review (style/conventions) | `sonnet` | Needs code understanding, not deep analysis |
|
|
||||||
| Security vulnerability analysis | `opus` | Requires nuanced judgment, high stakes |
|
|
||||||
| Issue triage and labeling | `haiku` or `sonnet` | Mostly classification tasks |
|
|
||||||
| Feature planning and breakdown | `sonnet` or `opus` | Needs strategic thinking |
|
|
||||||
| Batch processing (many items) | `haiku` or `sonnet` | Speed and cost matter at scale |
|
|
||||||
| Architectural exploration | `opus` | Complex reasoning about tradeoffs |
|
|
||||||
|
|
||||||
### Examples
|
|
||||||
|
|
||||||
These examples show recommended model configurations for different agent types:
|
|
||||||
|
|
||||||
**Code Reviewer Agent** - Use `sonnet`:
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: code-reviewer
|
|
||||||
model: sonnet
|
|
||||||
skills: gitea, code-review
|
|
||||||
---
|
|
||||||
```
|
|
||||||
Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.
|
|
||||||
|
|
||||||
**Security Auditor Agent** (hypothetical) - Use `opus`:
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: security-auditor
|
|
||||||
model: opus
|
|
||||||
skills: code-review # would add security-specific skills
|
|
||||||
---
|
|
||||||
```
|
|
||||||
Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.
|
|
||||||
|
|
||||||
**Formatting Agent** (hypothetical) - Use `haiku`:
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: markdown-formatter
|
|
||||||
model: haiku
|
|
||||||
skills: documentation
|
|
||||||
---
|
|
||||||
```
|
|
||||||
Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.
|
|
||||||
|
|
||||||
### Best Practices for Model Selection
|
|
||||||
|
|
||||||
1. **Start with `sonnet`** - It handles most agent tasks well
|
|
||||||
2. **Use `haiku` for volume** - When processing many items, speed and cost add up
|
|
||||||
3. **Reserve `opus` for judgment** - Use when errors are costly or reasoning is complex
|
|
||||||
4. **Avoid `inherit` by default** - Make a deliberate choice; `inherit` obscures the decision
|
|
||||||
5. **Consider the stakes** - Higher consequence tasks warrant more capable models
|
|
||||||
6. **Test with real tasks** - Verify the chosen model performs adequately
|
|
||||||
|
|
||||||
### When to Use `inherit`
|
|
||||||
|
|
||||||
The `inherit` option has legitimate uses:
|
|
||||||
|
|
||||||
- **Utility agents**: Small helpers that should match their caller's capability
|
|
||||||
- **Delegation chains**: When an agent spawns sub-agents that should stay consistent
|
|
||||||
- **Testing/development**: When you want to control model from the top level
|
|
||||||
|
|
||||||
However, most production agents should specify an explicit model.
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
### 1. Choose Skills Deliberately
|
|
||||||
|
|
||||||
Include only skills the agent needs. More skills = more context = potential confusion.
|
|
||||||
|
|
||||||
**Too many skills:**
|
|
||||||
```markdown
|
|
||||||
## Skills
|
|
||||||
- gitea
|
|
||||||
- issue-writing
|
|
||||||
- backlog-grooming
|
|
||||||
- roadmap-planning
|
|
||||||
- code-review
|
|
||||||
- testing
|
|
||||||
- documentation
|
|
||||||
- deployment
|
|
||||||
```
|
|
||||||
|
|
||||||
**Right-sized:**
|
|
||||||
```markdown
|
|
||||||
## Skills
|
|
||||||
- gitea
|
|
||||||
- issue-writing
|
|
||||||
- backlog-grooming
|
|
||||||
- roadmap-planning
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Define Clear Boundaries
|
|
||||||
|
|
||||||
Agents should know what they can and cannot do.
|
|
||||||
|
|
||||||
**Vague:**
|
|
||||||
```markdown
|
|
||||||
## Capabilities
|
|
||||||
This agent can help with project management.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Clear:**
|
|
||||||
```markdown
|
|
||||||
## Capabilities
|
|
||||||
This agent can:
|
|
||||||
- Review and improve existing issues
|
|
||||||
- Create new well-structured issues
|
|
||||||
- Analyze the backlog for gaps
|
|
||||||
|
|
||||||
This agent cannot:
|
|
||||||
- Merge pull requests
|
|
||||||
- Deploy code
|
|
||||||
- Make architectural decisions
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Set Behavioral Guardrails
|
|
||||||
|
|
||||||
Prevent agents from causing problems by setting explicit rules.
|
|
||||||
|
|
||||||
**Important behaviors to specify:**
|
|
||||||
- When to ask for approval
|
|
||||||
- What to do before making changes
|
|
||||||
- How to report results
|
|
||||||
- Error handling expectations
|
|
||||||
|
|
||||||
### 4. Match Persona to Purpose
|
|
||||||
|
|
||||||
The agent's name and description should align with its skills and capabilities.
|
|
||||||
|
|
||||||
**Mismatched:**
|
|
||||||
```markdown
|
|
||||||
# Security Agent
|
|
||||||
|
|
||||||
## Skills
|
|
||||||
- issue-writing
|
|
||||||
- documentation
|
|
||||||
```
|
|
||||||
|
|
||||||
**Aligned:**
|
|
||||||
```markdown
|
|
||||||
# Security Auditor Agent
|
|
||||||
|
|
||||||
## Skills
|
|
||||||
- security-scanning
|
|
||||||
- vulnerability-assessment
|
|
||||||
- code-review
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Keep Agents Focused
|
|
||||||
|
|
||||||
One agent = one role. If an agent does too many unrelated things, split it.
|
|
||||||
|
|
||||||
**Too broad:**
|
|
||||||
```markdown
|
|
||||||
# Everything Agent
|
|
||||||
Handles issues, code review, deployment, and customer support.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Focused:**
|
|
||||||
```markdown
|
|
||||||
# Product Manager Agent
|
|
||||||
Specialized for backlog management and roadmap planning.
|
|
||||||
```
|
|
||||||
|
|
||||||
## When to Create a New Agent
|
|
||||||
|
|
||||||
Create an agent when you need:
|
|
||||||
|
|
||||||
1. **Role-based expertise**: A recognizable persona improves outputs
|
|
||||||
2. **Skill composition**: Multiple skills work better together
|
|
||||||
3. **Context isolation**: Work shouldn't pollute main conversation
|
|
||||||
4. **Parallel capability**: Tasks can run independently
|
|
||||||
5. **Autonomous operation**: Agent should figure things out on its own
|
|
||||||
|
|
||||||
### Signs You Need a New Agent
|
|
||||||
|
|
||||||
- Commands repeatedly spawn similar skill combinations
|
|
||||||
- Tasks require deep exploration that pollutes context
|
|
||||||
- Work benefits from a specialist "persona"
|
|
||||||
- Batch processing would help
|
|
||||||
|
|
||||||
### Signs You Don't Need a New Agent
|
|
||||||
|
|
||||||
- Single skill is sufficient
|
|
||||||
- Task is simple and sequential
|
|
||||||
- Main context is helpful, not harmful
|
|
||||||
- No clear persona or role emerges
|
|
||||||
|
|
||||||
## Agent Lifecycle
|
|
||||||
|
|
||||||
### 1. Design
|
|
||||||
|
|
||||||
Define the agent's role:
|
|
||||||
- What persona makes sense?
|
|
||||||
- Which skills does it need?
|
|
||||||
- What can it do (and not do)?
|
|
||||||
- When should it be spawned?
|
|
||||||
|
|
||||||
### 2. Implement
|
|
||||||
|
|
||||||
Create the agent file:
|
|
||||||
- Clear name and description
|
|
||||||
- Appropriate skill list
|
|
||||||
- Specific capabilities
|
|
||||||
- Usage guidance
|
|
||||||
- Behavioral rules
|
|
||||||
|
|
||||||
### 3. Integrate
|
|
||||||
|
|
||||||
Connect the agent to workflows:
|
|
||||||
- Update commands that should spawn it
|
|
||||||
- Document in ARCHITECTURE.md
|
|
||||||
- Test with real tasks
|
|
||||||
|
|
||||||
### 4. Refine
|
|
||||||
|
|
||||||
Improve based on usage:
|
|
||||||
- Add/remove skills as needed
|
|
||||||
- Clarify capabilities
|
|
||||||
- Strengthen behavioral rules
|
|
||||||
- Update documentation
|
|
||||||
|
|
||||||
## Checklist: Before Submitting a New Agent
|
|
||||||
|
|
||||||
### Structure
|
|
||||||
- [ ] File is at `agents/<name>/AGENT.md`
|
|
||||||
- [ ] Name follows kebab-case convention
|
|
||||||
- [ ] Agent has a clear, recognizable role
|
|
||||||
|
|
||||||
### Frontmatter
|
|
||||||
- [ ] `name` and `description` fields are set
|
|
||||||
- [ ] `model` selection is deliberate (not just `inherit` by default)
|
|
||||||
- [ ] `skills` list is deliberate (not too many, not too few)
|
|
||||||
- [ ] Consider `disallowedTools` if agent should be restricted
|
|
||||||
- [ ] Consider `permissionMode` for trusted agents
|
|
||||||
- [ ] Consider `hooks` for validation or logging
|
|
||||||
|
|
||||||
### Content
|
|
||||||
- [ ] Capabilities are specific and achievable
|
|
||||||
- [ ] "When to Use" guidance is clear
|
|
||||||
- [ ] Behavioral rules prevent problems
|
|
||||||
|
|
||||||
### Integration
|
|
||||||
- [ ] Consider if built-in agents (Explore, Plan) could be used instead
|
|
||||||
- [ ] Agent is referenced by at least one command
|
|
||||||
- [ ] ARCHITECTURE.md is updated
|
|
||||||
|
|
||||||
## See Also
|
|
||||||
|
|
||||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How agents fit into the overall system
|
|
||||||
- [writing-skills.md](writing-skills.md): Creating the skills that agents use
|
|
||||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
|
||||||
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
|
||||||
@@ -1,731 +0,0 @@
|
|||||||
# Writing Commands
|
|
||||||
|
|
||||||
A guide to creating user-facing entry points that trigger workflows.
|
|
||||||
|
|
||||||
## What is a Command?
|
|
||||||
|
|
||||||
Commands are **user-facing entry points** that trigger workflows. Unlike skills (which encode knowledge) or agents (which execute tasks autonomously), commands define *what* to do—they orchestrate the workflow that users invoke directly.
|
|
||||||
|
|
||||||
Think of commands as the interface between users and the system. Users type `/work-issue 42` and the command defines the entire workflow: fetch issue, create branch, implement, commit, push, create PR.
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Commands live directly in the `commands/` directory as markdown files:
|
|
||||||
|
|
||||||
```
|
|
||||||
commands/
|
|
||||||
├── work-issue.md
|
|
||||||
├── dashboard.md
|
|
||||||
├── review-pr.md
|
|
||||||
├── create-issue.md
|
|
||||||
├── groom.md
|
|
||||||
├── roadmap.md
|
|
||||||
└── plan-issues.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why Flat Files?
|
|
||||||
|
|
||||||
Unlike skills and agents (which use folders), commands are single files because:
|
|
||||||
- Commands are self-contained workflow definitions
|
|
||||||
- No supporting files needed
|
|
||||||
- Simple naming: `/work-issue` maps to `work-issue.md`
|
|
||||||
|
|
||||||
## Command Document Structure
|
|
||||||
|
|
||||||
A well-structured command file has two parts:
|
|
||||||
|
|
||||||
### 1. Frontmatter (YAML Header)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
description: Brief description shown in command listings
|
|
||||||
argument-hint: <required-arg> [optional-arg]
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Required Fields
|
|
||||||
|
|
||||||
| Field | Purpose |
|
|
||||||
|-------|---------|
|
|
||||||
| `description` | One-line summary for help/listings |
|
|
||||||
|
|
||||||
#### Optional Fields
|
|
||||||
|
|
||||||
| Field | Purpose |
|
|
||||||
|-------|---------|
|
|
||||||
| `argument-hint` | Shows expected arguments (e.g., `<issue-number>`, `[title]`) |
|
|
||||||
| `model` | Model to use: `haiku`, `sonnet`, `opus`. Overrides session default. |
|
|
||||||
| `context` | Execution context. Use `fork` to run in isolated sub-agent context. |
|
|
||||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this command. |
|
|
||||||
| `allowed-tools` | Restrict which tools the command can use. |
|
|
||||||
|
|
||||||
### 2. Body (Markdown Instructions)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Command Title
|
|
||||||
|
|
||||||
Brief intro if needed.
|
|
||||||
|
|
||||||
1. **Step one**: What to do
|
|
||||||
2. **Step two**: What to do next
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
The body contains the workflow steps that Claude follows when the command is invoked.
|
|
||||||
|
|
||||||
## Complete Command Example
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Work on a Gitea issue. Fetches issue details and sets up branch.
|
|
||||||
argument-hint: <issue-number>
|
|
||||||
---
|
|
||||||
|
|
||||||
# Work on Issue #$1
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
1. **View the issue** to understand requirements
|
|
||||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
|
||||||
3. **Plan**: Use TodoWrite to break down the work
|
|
||||||
4. **Implement** the changes
|
|
||||||
5. **Commit** with message referencing the issue
|
|
||||||
6. **Push** the branch to origin
|
|
||||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Advanced Frontmatter Examples
|
|
||||||
|
|
||||||
**Command with specific model:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
description: Plan complex feature implementation.
|
|
||||||
argument-hint: <feature-description>
|
|
||||||
model: opus
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Command with isolated context (prevents context pollution):**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
description: Analyze codebase architecture deeply.
|
|
||||||
context: fork
|
|
||||||
model: haiku
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Command with hooks:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
description: Deploy to production environment.
|
|
||||||
hooks:
|
|
||||||
- type: PreToolUse
|
|
||||||
matcher: Bash
|
|
||||||
command: echo "Validating deployment command..."
|
|
||||||
- type: Stop
|
|
||||||
command: ./scripts/notify-deployment.sh
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Read-only command with tool restrictions:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
description: Generate codebase report without modifications.
|
|
||||||
allowed-tools:
|
|
||||||
- Read
|
|
||||||
- Glob
|
|
||||||
- Grep
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
## Argument Handling
|
|
||||||
|
|
||||||
Commands can accept arguments from the user. Arguments are passed via positional variables: `$1`, `$2`, etc.
|
|
||||||
|
|
||||||
### The ARGUMENTS Pattern
|
|
||||||
|
|
||||||
When users invoke a command with arguments:
|
|
||||||
```
|
|
||||||
/work-issue 42
|
|
||||||
```
|
|
||||||
|
|
||||||
The system provides the arguments via the `$1`, `$2`, etc. placeholders in the command body:
|
|
||||||
```markdown
|
|
||||||
# Work on Issue #$1
|
|
||||||
1. **View the issue** to understand requirements
|
|
||||||
```
|
|
||||||
|
|
||||||
Becomes:
|
|
||||||
```markdown
|
|
||||||
# Work on Issue #42
|
|
||||||
1. **View the issue** to understand requirements
|
|
||||||
```
|
|
||||||
|
|
||||||
### Argument Hints
|
|
||||||
|
|
||||||
Use `argument-hint` in frontmatter to document expected arguments:
|
|
||||||
|
|
||||||
| Pattern | Meaning |
|
|
||||||
|---------|---------|
|
|
||||||
| `<arg>` | Required argument |
|
|
||||||
| `[arg]` | Optional argument |
|
|
||||||
| `<arg1> <arg2>` | Multiple required |
|
|
||||||
| `[arg1] [arg2]` | Multiple optional |
|
|
||||||
| `<required> [optional]` | Mix of both |
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
```yaml
|
|
||||||
argument-hint: <issue-number> # One required
|
|
||||||
argument-hint: [issue-number] # One optional
|
|
||||||
argument-hint: <title> [description] # Required + optional
|
|
||||||
argument-hint: [title] or "batch" # Choice of modes
|
|
||||||
```
|
|
||||||
|
|
||||||
### Handling Optional Arguments
|
|
||||||
|
|
||||||
Commands often have different behavior based on whether arguments are provided:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Groom issues. Without argument, reviews all. With argument, grooms specific issue.
|
|
||||||
argument-hint: [issue-number]
|
|
||||||
---
|
|
||||||
|
|
||||||
# Groom Issues
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
## If issue number provided ($1):
|
|
||||||
1. **Fetch the issue** details
|
|
||||||
2. **Evaluate** against checklist
|
|
||||||
...
|
|
||||||
|
|
||||||
## If no argument (groom all):
|
|
||||||
1. **List open issues**
|
|
||||||
2. **Review each** against checklist
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### Multiple Modes
|
|
||||||
|
|
||||||
Some commands support distinct modes based on the first argument:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Create issues. Single or batch mode.
|
|
||||||
argument-hint: [title] or "batch"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Create Issue(s)
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
## Single Issue (default)
|
|
||||||
If title provided, create an issue with that title.
|
|
||||||
|
|
||||||
## Batch Mode
|
|
||||||
If $1 is "batch":
|
|
||||||
1. Ask user for the plan
|
|
||||||
2. Generate list of issues
|
|
||||||
3. Show for approval
|
|
||||||
4. Create each issue
|
|
||||||
```
|
|
||||||
|
|
||||||
## Including Skills
|
|
||||||
|
|
||||||
Commands include skills using the `@` file reference syntax. This automatically injects the skill content into the command context when the command is invoked.
|
|
||||||
|
|
||||||
### File Reference Syntax
|
|
||||||
|
|
||||||
Use the `@` prefix followed by the path to the skill file:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Groom Issues
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
@~/.claude/skills/backlog-grooming/SKILL.md
|
|
||||||
@~/.claude/skills/issue-writing/SKILL.md
|
|
||||||
|
|
||||||
1. **Fetch the issue** details
|
|
||||||
2. **Evaluate** against grooming checklist
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
When the command runs, the content of each referenced skill file is automatically loaded into context.
|
|
||||||
|
|
||||||
### Why File References?
|
|
||||||
|
|
||||||
**DO NOT** use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the skill content is available.
|
|
||||||
|
|
||||||
| Pattern | Behavior |
|
|
||||||
|---------|----------|
|
|
||||||
| `@~/.claude/skills/gitea/SKILL.md` | Content automatically injected |
|
|
||||||
| "Use the gitea skill" | Relies on auto-activation (~20% success) |
|
|
||||||
|
|
||||||
### When to Include Skills
|
|
||||||
|
|
||||||
| Include explicitly | Skip skill reference |
|
|
||||||
|-------------------|---------------------|
|
|
||||||
| CLI syntax is needed | Well-known commands |
|
|
||||||
| Core methodology required | Simple operations |
|
|
||||||
| Quality standards matter | One-off actions |
|
|
||||||
| Patterns should be followed | No domain knowledge needed |
|
|
||||||
|
|
||||||
## Invoking Agents
|
|
||||||
|
|
||||||
Commands can spawn agents for complex subtasks that benefit from skill composition or context isolation.
|
|
||||||
|
|
||||||
### Spawning Agents
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
For comprehensive backlog review, spawn the **product-manager** agent to:
|
|
||||||
- Review all open issues
|
|
||||||
- Categorize by readiness
|
|
||||||
- Propose improvements
|
|
||||||
```
|
|
||||||
|
|
||||||
### When to Spawn Agents
|
|
||||||
|
|
||||||
Spawn an agent when the command needs:
|
|
||||||
- **Parallel processing**: Multiple independent tasks
|
|
||||||
- **Context isolation**: Deep exploration that would pollute main context
|
|
||||||
- **Skill composition**: Multiple skills working together
|
|
||||||
- **Autonomous operation**: Let the agent figure out details
|
|
||||||
|
|
||||||
### Example: Conditional Agent Spawning
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Groom Issues
|
|
||||||
|
|
||||||
## If no argument (groom all):
|
|
||||||
For large backlogs (>10 issues), consider spawning the
|
|
||||||
product-manager agent to handle the review autonomously.
|
|
||||||
```
|
|
||||||
|
|
||||||
## Interactive Patterns
|
|
||||||
|
|
||||||
Commands often require user interaction for confirmation, choices, or input.
|
|
||||||
|
|
||||||
### Approval Workflows
|
|
||||||
|
|
||||||
Always ask for approval before significant actions:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
5. **Ask for approval** before creating issues
|
|
||||||
6. **Create issues** in order
|
|
||||||
```
|
|
||||||
|
|
||||||
Common approval points:
|
|
||||||
- Before creating/modifying resources (issues, PRs, files)
|
|
||||||
- Before executing destructive operations
|
|
||||||
- When presenting a plan that will be executed
|
|
||||||
|
|
||||||
### Presenting Choices
|
|
||||||
|
|
||||||
When the command leads to multiple possible actions:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
Ask the user what action to take:
|
|
||||||
- **Merge**: Approve and merge the PR
|
|
||||||
- **Request changes**: Leave feedback without merging
|
|
||||||
- **Comment only**: Add a comment for discussion
|
|
||||||
```
|
|
||||||
|
|
||||||
### Gathering Input
|
|
||||||
|
|
||||||
Some commands need to gather information from the user:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Batch Mode
|
|
||||||
If $1 is "batch":
|
|
||||||
1. **Ask user** for the plan/direction
|
|
||||||
2. Generate list of issues with titles and descriptions
|
|
||||||
3. Show for approval
|
|
||||||
```
|
|
||||||
|
|
||||||
### Presenting Results
|
|
||||||
|
|
||||||
Commands should clearly show what was done:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
7. **Update dependencies** with actual issue numbers after creation
|
|
||||||
8. **Present summary** with links to created issues
|
|
||||||
```
|
|
||||||
|
|
||||||
Good result presentations include:
|
|
||||||
- Tables for lists of items
|
|
||||||
- Links for created resources
|
|
||||||
- Summaries of changes made
|
|
||||||
- Next step suggestions
|
|
||||||
|
|
||||||
## Annotated Examples
|
|
||||||
|
|
||||||
Let's examine existing commands to understand effective patterns.
|
|
||||||
|
|
||||||
### Example 1: work-issue (Linear Workflow)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Work on a Gitea issue. Fetches issue details and sets up branch.
|
|
||||||
argument-hint: <issue-number>
|
|
||||||
---
|
|
||||||
|
|
||||||
# Work on Issue #$1
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
1. **View the issue** to understand requirements
|
|
||||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
|
||||||
3. **Plan**: Use TodoWrite to break down the work
|
|
||||||
4. **Implement** the changes
|
|
||||||
5. **Commit** with message referencing the issue
|
|
||||||
6. **Push** the branch to origin
|
|
||||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- **Linear workflow**: Clear numbered steps in order
|
|
||||||
- **Required argument**: `<issue-number>` means must provide
|
|
||||||
- **Variable substitution**: `$1` used throughout
|
|
||||||
- **Skill reference**: Uses gitea skill for CLI knowledge
|
|
||||||
- **Git integration**: Branch and push steps specified
|
|
||||||
|
|
||||||
### Example 2: dashboard (No Arguments)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Show dashboard of open issues, PRs awaiting review, and CI status.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Repository Dashboard
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
Fetch and display:
|
|
||||||
1. All open issues
|
|
||||||
2. All open PRs
|
|
||||||
|
|
||||||
Format as tables showing issue/PR number, title, and author.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- **No argument-hint**: Command takes no arguments
|
|
||||||
- **Output formatting**: Specifies how to present results
|
|
||||||
- **Aggregation**: Combines multiple data sources
|
|
||||||
- **Simple workflow**: Just fetch and display
|
|
||||||
|
|
||||||
### Example 3: groom (Optional Argument with Modes)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Groom and improve issues. Without argument, reviews all. With argument, grooms specific issue.
|
|
||||||
argument-hint: [issue-number]
|
|
||||||
---
|
|
||||||
|
|
||||||
# Groom Issues
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
@~/.claude/skills/backlog-grooming/SKILL.md
|
|
||||||
@~/.claude/skills/issue-writing/SKILL.md
|
|
||||||
|
|
||||||
## If issue number provided ($1):
|
|
||||||
1. **Fetch the issue** details
|
|
||||||
2. **Evaluate** against grooming checklist
|
|
||||||
3. **Suggest improvements** for:
|
|
||||||
- Title clarity
|
|
||||||
- Description completeness
|
|
||||||
- Acceptance criteria quality
|
|
||||||
4. **Ask user** if they want to apply changes
|
|
||||||
5. **Update issue** if approved
|
|
||||||
|
|
||||||
## If no argument (groom all):
|
|
||||||
1. **List open issues**
|
|
||||||
2. **Review each** against grooming checklist
|
|
||||||
3. **Categorize**: Ready / Needs work / Stale
|
|
||||||
4. **Present summary** table
|
|
||||||
5. **Offer to improve** issues that need work
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- **Optional argument**: `[issue-number]` with brackets
|
|
||||||
- **Mode switching**: Different behavior based on argument presence
|
|
||||||
- **Skill file references**: Uses `@~/.claude/skills/` to include multiple skills
|
|
||||||
- **Approval workflow**: "Ask user if they want to apply changes"
|
|
||||||
- **Categorization**: Groups items for presentation
|
|
||||||
|
|
||||||
### Example 4: plan-issues (Complex Workflow)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Plan and create issues for a feature. Breaks down work into well-structured issues.
|
|
||||||
argument-hint: <feature-description>
|
|
||||||
---
|
|
||||||
|
|
||||||
# Plan Feature: $1
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
@~/.claude/skills/roadmap-planning/SKILL.md
|
|
||||||
@~/.claude/skills/issue-writing/SKILL.md
|
|
||||||
|
|
||||||
1. **Understand the feature**: Analyze what "$1" involves
|
|
||||||
2. **Explore the codebase** if needed to understand context
|
|
||||||
3. **Break down** into discrete, actionable issues
|
|
||||||
4. **Present the plan**:
|
|
||||||
```
|
|
||||||
## Proposed Issues for: $1
|
|
||||||
|
|
||||||
1. [Title] - Brief description
|
|
||||||
Dependencies: none
|
|
||||||
...
|
|
||||||
```
|
|
||||||
5. **Ask for approval** before creating issues
|
|
||||||
6. **Create issues** in order
|
|
||||||
7. **Update dependencies** with actual issue numbers
|
|
||||||
8. **Present summary** with links to created issues
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- **Multi-skill composition**: Includes three skills via `@~/.claude/skills/`
|
|
||||||
- **Codebase exploration**: May need to understand context
|
|
||||||
- **Structured output**: Template for presenting the plan
|
|
||||||
- **Two-phase execution**: Plan first, then execute after approval
|
|
||||||
- **Dependency management**: Creates issues in order, updates references
|
|
||||||
|
|
||||||
### Example 5: review-pr (Action Choices)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
description: Review a Gitea pull request. Fetches PR details, diff, and comments.
|
|
||||||
argument-hint: <pr-number>
|
|
||||||
---
|
|
||||||
|
|
||||||
# Review PR #$1
|
|
||||||
|
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
|
||||||
|
|
||||||
1. **View PR details** including description and metadata
|
|
||||||
2. **Get the diff** to review the changes
|
|
||||||
|
|
||||||
Review the changes and provide feedback on:
|
|
||||||
- Code quality
|
|
||||||
- Potential bugs
|
|
||||||
- Test coverage
|
|
||||||
- Documentation
|
|
||||||
|
|
||||||
Ask the user what action to take:
|
|
||||||
- **Merge**: Approve and merge the PR
|
|
||||||
- **Request changes**: Leave feedback without merging
|
|
||||||
- **Comment only**: Add a comment for discussion
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- **Information gathering**: Fetches context before analysis
|
|
||||||
- **Review criteria**: Checklist of what to examine
|
|
||||||
- **Action menu**: Clear choices with explanations
|
|
||||||
- **User decides outcome**: Command presents options, user chooses
|
|
||||||
|
|
||||||
## Naming Conventions
|
|
||||||
|
|
||||||
### Command File Names
|
|
||||||
|
|
||||||
- Use **kebab-case**: `work-issue.md`, `plan-issues.md`
|
|
||||||
- Use **verbs or verb phrases**: Commands are actions
|
|
||||||
- Be **concise**: 1-3 words is ideal
|
|
||||||
- Match the **invocation**: `/work-issue` → `work-issue.md`
|
|
||||||
|
|
||||||
Good names:
|
|
||||||
- `work-issue` - Action + target
|
|
||||||
- `dashboard` - What it shows
|
|
||||||
- `review-pr` - Action + target
|
|
||||||
- `plan-issues` - Action + target
|
|
||||||
- `groom` - Action (target implied)
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- `issue-work` - Noun-first is awkward
|
|
||||||
- `do-stuff` - Too vague
|
|
||||||
- `manage-issues-and-prs` - Too long
|
|
||||||
|
|
||||||
### Command Titles
|
|
||||||
|
|
||||||
The H1 title can be more descriptive than the filename:
|
|
||||||
|
|
||||||
| Filename | Title |
|
|
||||||
|----------|-------|
|
|
||||||
| `work-issue.md` | Work on Issue #$1 |
|
|
||||||
| `dashboard.md` | Repository Dashboard |
|
|
||||||
| `plan-issues.md` | Plan Feature: $1 |
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
### 1. Design Clear Workflows
|
|
||||||
|
|
||||||
Each step should be unambiguous:
|
|
||||||
|
|
||||||
**Vague:**
|
|
||||||
```markdown
|
|
||||||
1. Handle the issue
|
|
||||||
2. Do the work
|
|
||||||
3. Finish up
|
|
||||||
```
|
|
||||||
|
|
||||||
**Clear:**
|
|
||||||
```markdown
|
|
||||||
1. **View the issue** to understand requirements
|
|
||||||
2. **Create a branch**: `git checkout -b issue-$1-<title>`
|
|
||||||
3. **Plan**: Use TodoWrite to break down the work
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Show Don't Tell
|
|
||||||
|
|
||||||
Include actual commands and expected outputs:
|
|
||||||
|
|
||||||
**Telling:**
|
|
||||||
```markdown
|
|
||||||
List the open issues.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Showing:**
|
|
||||||
```markdown
|
|
||||||
Fetch all open issues and format as table:
|
|
||||||
| # | Title | Author |
|
|
||||||
|---|-------|--------|
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Always Ask Before Acting
|
|
||||||
|
|
||||||
Never modify resources without user approval:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
4. **Present plan** for approval
|
|
||||||
5. **If approved**, create the issues
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Handle Edge Cases
|
|
||||||
|
|
||||||
Consider what happens when things are empty or unexpected:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## If no argument (groom all):
|
|
||||||
1. **List open issues**
|
|
||||||
2. If no issues found, report "No open issues to groom"
|
|
||||||
3. Otherwise, **review each** against checklist
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Provide Helpful Output
|
|
||||||
|
|
||||||
End with useful information:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
8. **Present summary** with:
|
|
||||||
- Links to created issues
|
|
||||||
- Dependency graph
|
|
||||||
- Suggested next steps
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Keep Commands Focused
|
|
||||||
|
|
||||||
One command = one workflow. If doing multiple unrelated things, split into separate commands.
|
|
||||||
|
|
||||||
**Too broad:**
|
|
||||||
```markdown
|
|
||||||
# Manage Everything
|
|
||||||
Handle issues, PRs, deployments, and documentation...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Focused:**
|
|
||||||
```markdown
|
|
||||||
# Review PR #$1
|
|
||||||
Review and take action on a pull request...
|
|
||||||
```
|
|
||||||
|
|
||||||
## When to Create a Command
|
|
||||||
|
|
||||||
Create a command when you have:
|
|
||||||
|
|
||||||
1. **Repeatable workflow**: Same steps used multiple times
|
|
||||||
2. **User-initiated action**: User explicitly triggers it
|
|
||||||
3. **Clear start and end**: Workflow has defined boundaries
|
|
||||||
4. **Consistent behavior needed**: Should work the same every time
|
|
||||||
|
|
||||||
### Signs You Need a New Command
|
|
||||||
|
|
||||||
- You're explaining the same workflow repeatedly
|
|
||||||
- Users would benefit from a single invocation
|
|
||||||
- Multiple tools need orchestration
|
|
||||||
- Approval checkpoints are needed
|
|
||||||
|
|
||||||
### Signs You Don't Need a Command
|
|
||||||
|
|
||||||
- It's a one-time action
|
|
||||||
- No workflow orchestration needed
|
|
||||||
- A skill reference is sufficient
|
|
||||||
- An agent could handle it autonomously
|
|
||||||
|
|
||||||
## Command Lifecycle
|
|
||||||
|
|
||||||
### 1. Design
|
|
||||||
|
|
||||||
Define the workflow:
|
|
||||||
- What triggers it?
|
|
||||||
- What arguments does it need?
|
|
||||||
- What steps are involved?
|
|
||||||
- Where are approval points?
|
|
||||||
- What does success look like?
|
|
||||||
|
|
||||||
### 2. Implement
|
|
||||||
|
|
||||||
Create the command file:
|
|
||||||
- Clear frontmatter
|
|
||||||
- Step-by-step workflow
|
|
||||||
- Skill references where needed
|
|
||||||
- Approval checkpoints
|
|
||||||
- Output formatting
|
|
||||||
|
|
||||||
### 3. Test
|
|
||||||
|
|
||||||
Verify the workflow:
|
|
||||||
- Run with typical arguments
|
|
||||||
- Test edge cases (no args, invalid args)
|
|
||||||
- Confirm approval points work
|
|
||||||
- Check output formatting
|
|
||||||
|
|
||||||
### 4. Document
|
|
||||||
|
|
||||||
Update references:
|
|
||||||
- Add to ARCHITECTURE.md table
|
|
||||||
- Update README if user-facing
|
|
||||||
- Note any skill/agent dependencies
|
|
||||||
|
|
||||||
## Checklist: Before Submitting a New Command
|
|
||||||
|
|
||||||
### Structure
|
|
||||||
- [ ] File is at `commands/<name>.md`
|
|
||||||
- [ ] Name follows kebab-case verb convention
|
|
||||||
|
|
||||||
### Frontmatter (Required)
|
|
||||||
- [ ] `description` is set with clear one-line summary
|
|
||||||
- [ ] `argument-hint` is set (if command takes arguments)
|
|
||||||
|
|
||||||
### Frontmatter (Consider)
|
|
||||||
- [ ] `model` if command benefits from specific model (e.g., `opus` for complex planning)
|
|
||||||
- [ ] `context: fork` if command does heavy exploration that would pollute context
|
|
||||||
- [ ] `allowed-tools` if command should be restricted to certain tools
|
|
||||||
- [ ] `hooks` if command needs validation or post-execution actions
|
|
||||||
|
|
||||||
### Content
|
|
||||||
- [ ] Workflow steps are clear and numbered
|
|
||||||
- [ ] Commands and tools are specified explicitly
|
|
||||||
- [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
|
|
||||||
- [ ] Approval points exist before significant actions
|
|
||||||
- [ ] Edge cases are handled (no data, invalid input)
|
|
||||||
- [ ] Output formatting is specified
|
|
||||||
|
|
||||||
### Integration
|
|
||||||
- [ ] ARCHITECTURE.md is updated with new command
|
|
||||||
|
|
||||||
## See Also
|
|
||||||
|
|
||||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How commands fit into the overall system
|
|
||||||
- [writing-skills.md](writing-skills.md): Creating skills that commands reference
|
|
||||||
- [writing-agents.md](writing-agents.md): Creating agents that commands spawn
|
|
||||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
|
||||||
@@ -1,578 +0,0 @@
|
|||||||
# Writing Skills
|
|
||||||
|
|
||||||
A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
|
|
||||||
|
|
||||||
> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills
|
|
||||||
|
|
||||||
## What is a Skill?
|
|
||||||
|
|
||||||
Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.
|
|
||||||
|
|
||||||
## YAML Frontmatter (Required)
|
|
||||||
|
|
||||||
Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.
|
|
||||||
|
|
||||||
### Format Requirements
|
|
||||||
|
|
||||||
- Must start with `---` on **line 1** (no blank lines before it)
|
|
||||||
- Must end with `---` before the markdown content
|
|
||||||
- Use spaces for indentation (not tabs)
|
|
||||||
|
|
||||||
### Required Fields
|
|
||||||
|
|
||||||
| Field | Required | Description |
|
|
||||||
|-------|----------|-------------|
|
|
||||||
| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
|
|
||||||
| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |
|
|
||||||
|
|
||||||
### Optional Fields
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. Supports YAML-style lists. |
|
|
||||||
| `model` | Specific model to use when skill is active (e.g., `sonnet`, `opus`, `haiku`). |
|
|
||||||
| `user-invocable` | Whether the skill appears in the `/` command menu. Defaults to `true`. Set to `false` for reference-only skills. |
|
|
||||||
| `context` | Execution context. Use `fork` to run skill in an isolated sub-agent context, preventing context pollution. |
|
|
||||||
| `agent` | Agent type to use for execution. Allows skills to specify which agent handles them. |
|
|
||||||
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this skill's lifecycle. |
|
|
||||||
|
|
||||||
### Writing Effective Descriptions
|
|
||||||
|
|
||||||
The `description` field determines when Claude applies the skill. A good description answers:
|
|
||||||
|
|
||||||
1. **What does this skill do?** List specific capabilities.
|
|
||||||
2. **When should Claude use it?** Include trigger terms users would mention.
|
|
||||||
|
|
||||||
**Bad (too vague):**
|
|
||||||
```yaml
|
|
||||||
description: Helps with documents
|
|
||||||
```
|
|
||||||
|
|
||||||
**Good (specific with trigger terms):**
|
|
||||||
```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, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
|
|
||||||
```
|
|
||||||
|
|
||||||
### Example Frontmatter
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: gitea
|
|
||||||
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.
|
|
||||||
user-invocable: false
|
|
||||||
---
|
|
||||||
|
|
||||||
# Gitea CLI (tea)
|
|
||||||
|
|
||||||
[Rest of skill content...]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Advanced Frontmatter Examples
|
|
||||||
|
|
||||||
**Reference skill (not directly invocable):**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: gitea
|
|
||||||
description: CLI reference for Gitea operations.
|
|
||||||
user-invocable: false
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Skill with isolated context:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: codebase-analysis
|
|
||||||
description: Deep codebase exploration and analysis.
|
|
||||||
context: fork
|
|
||||||
model: haiku
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Skill with tool restrictions (YAML-style list):**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: read-only-review
|
|
||||||
description: Code review without modifications.
|
|
||||||
allowed-tools:
|
|
||||||
- Read
|
|
||||||
- Glob
|
|
||||||
- Grep
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Skill with hooks:**
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: database-operations
|
|
||||||
description: Database schema and migration operations.
|
|
||||||
hooks:
|
|
||||||
- type: PreToolUse
|
|
||||||
matcher: Bash
|
|
||||||
command: echo "Validating database command..."
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
## Subagents and Skills
|
|
||||||
|
|
||||||
Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: code-reviewer
|
|
||||||
description: Review code for quality and best practices
|
|
||||||
skills: gitea, code-review
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
Skills live in the `skills/` directory, each in its own folder:
|
|
||||||
|
|
||||||
```
|
|
||||||
skills/
|
|
||||||
├── gitea/
|
|
||||||
│ └── SKILL.md
|
|
||||||
├── issue-writing/
|
|
||||||
│ └── SKILL.md
|
|
||||||
├── backlog-grooming/
|
|
||||||
│ └── SKILL.md
|
|
||||||
└── roadmap-planning/
|
|
||||||
└── SKILL.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why SKILL.md?
|
|
||||||
|
|
||||||
The uppercase `SKILL.md` filename:
|
|
||||||
- Makes the skill file immediately visible in directory listings
|
|
||||||
- Follows a consistent convention across all skills
|
|
||||||
- Clearly identifies the primary file in a skill folder
|
|
||||||
|
|
||||||
### Supporting Files (Optional)
|
|
||||||
|
|
||||||
A skill folder can contain additional files if needed:
|
|
||||||
|
|
||||||
```
|
|
||||||
skills/
|
|
||||||
└── complex-skill/
|
|
||||||
├── SKILL.md # Main skill document (required)
|
|
||||||
├── templates/ # Template files
|
|
||||||
│ └── example.md
|
|
||||||
└── examples/ # Extended examples
|
|
||||||
└── case-study.md
|
|
||||||
```
|
|
||||||
|
|
||||||
However, prefer keeping everything in `SKILL.md` when possible—it's easier to maintain and reference.
|
|
||||||
|
|
||||||
## Skill Document Structure
|
|
||||||
|
|
||||||
A well-structured `SKILL.md` follows this pattern:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Skill Name
|
|
||||||
|
|
||||||
Brief description of what this skill covers.
|
|
||||||
|
|
||||||
## Core Concepts
|
|
||||||
Explain the 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.
|
|
||||||
```
|
|
||||||
|
|
||||||
Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
|
|
||||||
|
|
||||||
## How Skills are Discovered and Triggered
|
|
||||||
|
|
||||||
Skills are **model-invoked**: Claude decides which skills to use based on your request.
|
|
||||||
|
|
||||||
### Discovery Process
|
|
||||||
|
|
||||||
1. **At startup**: Claude loads only the `name` and `description` of each available skill
|
|
||||||
2. **On request**: Claude matches your request against skill descriptions using semantic similarity
|
|
||||||
3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
|
|
||||||
|
|
||||||
### Hot Reload
|
|
||||||
|
|
||||||
Skills support **automatic hot-reload**. When you create or modify a skill file in `~/.claude/skills/` or `.claude/skills/`, the changes are immediately available without restarting Claude Code. This enables rapid iteration when developing skills.
|
|
||||||
|
|
||||||
### Visibility in Command Menu
|
|
||||||
|
|
||||||
By default, skills in `/skills/` directories appear in the `/` slash command menu. Users can invoke them directly like commands. To hide a skill from the menu (e.g., for reference-only skills), add `user-invocable: false` to the frontmatter.
|
|
||||||
|
|
||||||
### Subagent Access
|
|
||||||
|
|
||||||
Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: product-manager
|
|
||||||
description: Manages backlog and roadmap
|
|
||||||
skills: gitea, issue-writing, backlog-grooming, roadmap-planning
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.
|
|
||||||
|
|
||||||
### Skills Can Reference Other Skills
|
|
||||||
|
|
||||||
Skills can mention other skills for related knowledge:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Roadmap Planning
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
When creating issues, follow the patterns in the **issue-writing** skill.
|
|
||||||
Use **gitea** commands to create the issues.
|
|
||||||
```
|
|
||||||
|
|
||||||
This creates a natural knowledge hierarchy without duplicating content.
|
|
||||||
|
|
||||||
## Naming Conventions
|
|
||||||
|
|
||||||
### Skill Folder Names
|
|
||||||
|
|
||||||
- Use **kebab-case**: `issue-writing`, `backlog-grooming`
|
|
||||||
- Be **descriptive**: name should indicate the skill's domain
|
|
||||||
- Be **concise**: 2-3 words is ideal
|
|
||||||
- Avoid generic names: `utils`, `helpers`, `common`
|
|
||||||
|
|
||||||
Good names:
|
|
||||||
- `gitea` - Tool-specific knowledge
|
|
||||||
- `issue-writing` - Activity-focused
|
|
||||||
- `backlog-grooming` - Process-focused
|
|
||||||
- `roadmap-planning` - Task-focused
|
|
||||||
|
|
||||||
### Skill Titles
|
|
||||||
|
|
||||||
The H1 title in `SKILL.md` should match the folder name in Title Case:
|
|
||||||
|
|
||||||
| Folder | Title |
|
|
||||||
|--------|-------|
|
|
||||||
| `gitea` | Forgejo CLI (fj) |
|
|
||||||
| `issue-writing` | Issue Writing |
|
|
||||||
| `backlog-grooming` | Backlog Grooming |
|
|
||||||
| `roadmap-planning` | Roadmap Planning |
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
### 1. Keep Skills Focused
|
|
||||||
|
|
||||||
Each skill should cover **one domain, one concern**. If your skill document is getting long or covers multiple unrelated topics, consider splitting it.
|
|
||||||
|
|
||||||
**Too broad:**
|
|
||||||
```markdown
|
|
||||||
# Project Management
|
|
||||||
How to manage issues, PRs, releases, and documentation...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Better:**
|
|
||||||
```markdown
|
|
||||||
# Issue Writing
|
|
||||||
How to write clear, actionable issues.
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Be Specific, Not Vague
|
|
||||||
|
|
||||||
Provide concrete patterns, not abstract principles.
|
|
||||||
|
|
||||||
**Vague:**
|
|
||||||
```markdown
|
|
||||||
## Writing Good Titles
|
|
||||||
Titles should be clear and descriptive.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Specific:**
|
|
||||||
```markdown
|
|
||||||
## Writing Good Titles
|
|
||||||
- Start with action verb: "Add", "Fix", "Update", "Remove"
|
|
||||||
- Be specific: "Add user authentication" not "Auth stuff"
|
|
||||||
- Keep under 60 characters
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Include Actionable Examples
|
|
||||||
|
|
||||||
Every guideline should have an example showing what it looks like in practice.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
### Acceptance Criteria
|
|
||||||
|
|
||||||
Good criteria are:
|
|
||||||
- **Specific**: "User sees error message" not "Handle errors"
|
|
||||||
- **Testable**: Can verify pass/fail
|
|
||||||
- **User-focused**: What the user experiences
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
- [ ] Login form validates email format before submission
|
|
||||||
- [ ] Invalid credentials show "Invalid email or password" message
|
|
||||||
- [ ] Successful login redirects to dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Use Templates for Repeatability
|
|
||||||
|
|
||||||
When the skill involves creating structured content, provide copy-paste templates:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
### Feature Request Template
|
|
||||||
|
|
||||||
\```markdown
|
|
||||||
## Summary
|
|
||||||
What feature and why it's valuable.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
- [ ] Criterion 1
|
|
||||||
- [ ] Criterion 2
|
|
||||||
|
|
||||||
## Context
|
|
||||||
Additional background or references.
|
|
||||||
\```
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Include Checklists for Verification
|
|
||||||
|
|
||||||
Checklists help ensure consistent quality:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Grooming Checklist
|
|
||||||
|
|
||||||
For each issue, verify:
|
|
||||||
- [ ] Starts with action verb
|
|
||||||
- [ ] Has acceptance criteria
|
|
||||||
- [ ] Scope is clear
|
|
||||||
- [ ] Dependencies identified
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Document Common Mistakes
|
|
||||||
|
|
||||||
Help avoid pitfalls by documenting what goes wrong:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Common Mistakes
|
|
||||||
|
|
||||||
### Vague Titles
|
|
||||||
- Bad: "Fix bug"
|
|
||||||
- Good: "Fix login form validation on empty email"
|
|
||||||
|
|
||||||
### Missing Acceptance Criteria
|
|
||||||
Every issue needs specific, testable criteria.
|
|
||||||
```
|
|
||||||
|
|
||||||
### 7. Keep It Current
|
|
||||||
|
|
||||||
Skills should reflect current practices. When workflows change:
|
|
||||||
- Update the skill document
|
|
||||||
- Remove obsolete patterns
|
|
||||||
- Add new best practices
|
|
||||||
|
|
||||||
## Annotated Examples
|
|
||||||
|
|
||||||
Let's examine the existing skills to understand effective patterns.
|
|
||||||
|
|
||||||
### Example 1: gitea (Tool Reference)
|
|
||||||
|
|
||||||
The `gitea` skill is a **tool reference**—it documents how to use a specific CLI tool.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Forgejo CLI (fj)
|
|
||||||
|
|
||||||
Command-line interface for interacting with Forgejo repositories.
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
The `tea` CLI authenticates via `tea auth login`. Credentials are stored locally.
|
|
||||||
|
|
||||||
## Common Commands
|
|
||||||
|
|
||||||
### Issues
|
|
||||||
\```bash
|
|
||||||
# List issues
|
|
||||||
tea issue search -s open # Open issues
|
|
||||||
tea issue search -s closed # Closed issues
|
|
||||||
...
|
|
||||||
\```
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- Organized by feature area (Issues, Pull Requests, Repository)
|
|
||||||
- Includes actual command syntax with comments
|
|
||||||
- Covers common use cases, not exhaustive documentation
|
|
||||||
- Tips section for non-obvious behaviors
|
|
||||||
|
|
||||||
### Example 2: issue-writing (Process Knowledge)
|
|
||||||
|
|
||||||
The `issue-writing` skill is **process knowledge**—it teaches how to do something well.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Issue Writing
|
|
||||||
|
|
||||||
How to write clear, actionable issues.
|
|
||||||
|
|
||||||
## Issue Structure
|
|
||||||
|
|
||||||
### Title
|
|
||||||
- Start with action verb: "Add", "Fix", "Update", "Remove"
|
|
||||||
- Be specific: "Add user authentication" not "Auth stuff"
|
|
||||||
- Keep under 60 characters
|
|
||||||
|
|
||||||
### Description
|
|
||||||
\```markdown
|
|
||||||
## Summary
|
|
||||||
One paragraph explaining what and why.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
- [ ] Specific, testable requirement
|
|
||||||
...
|
|
||||||
\```
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- Clear guidelines with specific rules
|
|
||||||
- Templates for different issue types
|
|
||||||
- Good/bad examples for each guideline
|
|
||||||
- Covers the full lifecycle (structure, criteria, labels, dependencies)
|
|
||||||
|
|
||||||
### Example 3: backlog-grooming (Workflow Checklist)
|
|
||||||
|
|
||||||
The `backlog-grooming` skill is a **workflow checklist**—it provides a systematic process.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Backlog Grooming
|
|
||||||
|
|
||||||
How to review and improve existing issues.
|
|
||||||
|
|
||||||
## Grooming Checklist
|
|
||||||
|
|
||||||
For each issue, verify:
|
|
||||||
|
|
||||||
### 1. Title Clarity
|
|
||||||
- [ ] Starts with action verb
|
|
||||||
- [ ] Specific and descriptive
|
|
||||||
- [ ] Understandable without reading description
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- Structured as a checklist with categories
|
|
||||||
- Each item is a yes/no verification
|
|
||||||
- Includes workflow steps (Grooming Workflow section)
|
|
||||||
- Questions to guide decision-making
|
|
||||||
|
|
||||||
### Example 4: roadmap-planning (Strategy Guide)
|
|
||||||
|
|
||||||
The `roadmap-planning` skill is a **strategy guide**—it teaches how to think about a problem.
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Roadmap Planning
|
|
||||||
|
|
||||||
How to plan features and create issues for implementation.
|
|
||||||
|
|
||||||
## Planning Process
|
|
||||||
|
|
||||||
### 1. Understand the Goal
|
|
||||||
- What capability or improvement is needed?
|
|
||||||
- Who benefits and how?
|
|
||||||
- What's the success criteria?
|
|
||||||
|
|
||||||
### 2. Break Down the Work
|
|
||||||
- Identify distinct components
|
|
||||||
- Define boundaries between pieces
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key patterns:**
|
|
||||||
- Process-oriented with numbered steps
|
|
||||||
- Multiple breakdown strategies (by layer, by user story, by component)
|
|
||||||
- Concrete examples showing the pattern applied
|
|
||||||
- Questions to guide planning decisions
|
|
||||||
|
|
||||||
## When to Create a New Skill
|
|
||||||
|
|
||||||
Create a skill when you find yourself:
|
|
||||||
|
|
||||||
1. **Explaining the same concepts repeatedly** across different conversations
|
|
||||||
2. **Wanting consistent quality** in a specific area
|
|
||||||
3. **Building up domain expertise** that should persist
|
|
||||||
4. **Needing a reusable reference** for commands or agents
|
|
||||||
|
|
||||||
### Signs You Need a New Skill
|
|
||||||
|
|
||||||
- You're copy-pasting the same guidelines
|
|
||||||
- Multiple commands need the same knowledge
|
|
||||||
- Quality is inconsistent without explicit guidance
|
|
||||||
- There's a clear domain that doesn't fit existing skills
|
|
||||||
|
|
||||||
### Signs You Don't Need a New Skill
|
|
||||||
|
|
||||||
- The knowledge is only used once
|
|
||||||
- It's already covered by an existing skill
|
|
||||||
- It's too generic to be actionable
|
|
||||||
- It's better as part of a command's instructions
|
|
||||||
|
|
||||||
## Skill Lifecycle
|
|
||||||
|
|
||||||
### 1. Draft
|
|
||||||
|
|
||||||
Start with the essential content:
|
|
||||||
- Core patterns and templates
|
|
||||||
- Key guidelines
|
|
||||||
- A few examples
|
|
||||||
|
|
||||||
### 2. Refine
|
|
||||||
|
|
||||||
As you use the skill, improve it:
|
|
||||||
- Add examples from real usage
|
|
||||||
- Clarify ambiguous guidelines
|
|
||||||
- Remove unused content
|
|
||||||
|
|
||||||
### 3. Maintain
|
|
||||||
|
|
||||||
Keep skills current:
|
|
||||||
- Update when practices change
|
|
||||||
- Remove obsolete patterns
|
|
||||||
- Add newly discovered best practices
|
|
||||||
|
|
||||||
## Checklist: Before Submitting a New Skill
|
|
||||||
|
|
||||||
### Frontmatter (Critical)
|
|
||||||
- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
|
|
||||||
- [ ] `name` field uses lowercase letters, numbers, and hyphens only
|
|
||||||
- [ ] `name` matches the directory name
|
|
||||||
- [ ] `description` lists specific capabilities
|
|
||||||
- [ ] `description` includes "Use when..." with trigger terms
|
|
||||||
|
|
||||||
### Optional Frontmatter (Consider)
|
|
||||||
- [ ] `user-invocable: false` if skill is reference-only (e.g., CLI docs)
|
|
||||||
- [ ] `context: fork` if skill does heavy exploration that would pollute context
|
|
||||||
- [ ] `model` if skill benefits from a specific model (e.g., `haiku` for speed)
|
|
||||||
- [ ] `allowed-tools` if skill should be restricted to certain tools
|
|
||||||
- [ ] `hooks` if skill needs validation or logging
|
|
||||||
|
|
||||||
### File Structure
|
|
||||||
- [ ] File is at `skills/<name>/SKILL.md`
|
|
||||||
- [ ] Name follows kebab-case convention
|
|
||||||
|
|
||||||
### Content Quality
|
|
||||||
- [ ] Skill focuses on a single domain
|
|
||||||
- [ ] Guidelines are specific and actionable
|
|
||||||
- [ ] Examples illustrate each major point
|
|
||||||
- [ ] Templates are provided where appropriate
|
|
||||||
- [ ] Common mistakes are documented
|
|
||||||
|
|
||||||
### Integration
|
|
||||||
- [ ] Skill is listed in relevant subagent `skills` fields if needed
|
|
||||||
|
|
||||||
## See Also
|
|
||||||
|
|
||||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How skills fit into the overall system
|
|
||||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
|
||||||
@@ -4,7 +4,7 @@ This folder captures learnings from retrospectives and day-to-day work. Learning
|
|||||||
|
|
||||||
1. **Historical record**: What we learned and when
|
1. **Historical record**: What we learned and when
|
||||||
2. **Governance reference**: Why we work the way we do
|
2. **Governance reference**: Why we work the way we do
|
||||||
3. **Encoding source**: Input that gets encoded into skills, commands, and agents
|
3. **Encoding source**: Input that gets encoded into skills and agents
|
||||||
|
|
||||||
## The Learning Flow
|
## The Learning Flow
|
||||||
|
|
||||||
@@ -17,7 +17,7 @@ Experience → Learning captured → Encoded into system → Knowledge is action
|
|||||||
- Periodic review
|
- Periodic review
|
||||||
```
|
```
|
||||||
|
|
||||||
Learnings are **not** the final destination. They are inputs that get encoded into commands, skills, and agents where Claude can actually use them. But we keep the learning file as a record of *why* we encoded what we did.
|
Learnings are **not** the final destination. They are inputs that get encoded into skills and agents where Claude can actually use them. But we keep the learning file as a record of *why* we encoded what we did.
|
||||||
|
|
||||||
## Writing a Learning
|
## Writing a Learning
|
||||||
|
|
||||||
@@ -40,8 +40,7 @@ The insight we gained. Be specific and actionable.
|
|||||||
Where this learning has been (or will be) encoded:
|
Where this learning has been (or will be) encoded:
|
||||||
|
|
||||||
- `skills/xxx/SKILL.md` - What was added/changed
|
- `skills/xxx/SKILL.md` - What was added/changed
|
||||||
- `commands/xxx.md` - What was added/changed
|
- `agents/xxx/AGENT.md` - What was added/changed
|
||||||
- `agents/xxx/agent.md` - What was added/changed
|
|
||||||
|
|
||||||
If not yet encoded, note: "Pending: Issue #XX"
|
If not yet encoded, note: "Pending: Issue #XX"
|
||||||
|
|
||||||
@@ -54,7 +53,7 @@ What this learning means for how we work going forward. This is the "why" that j
|
|||||||
|
|
||||||
1. **Capture the learning** in this folder
|
1. **Capture the learning** in this folder
|
||||||
2. **Create an issue** to encode it into the appropriate location
|
2. **Create an issue** to encode it into the appropriate location
|
||||||
3. **Update the skill/command/agent** with the encoded knowledge
|
3. **Update the skill/agent** with the encoded knowledge
|
||||||
4. **Update the learning file** with the "Encoded In" references
|
4. **Update the learning file** with the "Encoded In" references
|
||||||
|
|
||||||
The goal: Claude should be able to *use* the learning, not just *read* about it.
|
The goal: Claude should be able to *use* the learning, not just *read* about it.
|
||||||
@@ -63,8 +62,8 @@ The goal: Claude should be able to *use* the learning, not just *read* about it.
|
|||||||
|
|
||||||
| Learning Type | Encode In |
|
| Learning Type | Encode In |
|
||||||
|---------------|-----------|
|
|---------------|-----------|
|
||||||
| How to use a tool | `skills/` |
|
| How to use a tool | `skills/` (background skill) |
|
||||||
| Workflow improvement | `commands/` |
|
| Workflow improvement | `skills/` (user-invocable skill) |
|
||||||
| Subtask behavior | `agents/` |
|
| Subtask behavior | `agents/` |
|
||||||
| Organization belief | `manifesto.md` |
|
| Organization belief | `manifesto.md` |
|
||||||
| Product direction | `vision.md` (in product repo) |
|
| Product direction | `vision.md` (in product repo) |
|
||||||
|
|||||||
@@ -1,7 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
|
name: arch-refine-issue
|
||||||
|
description: >
|
||||||
|
Refine an issue with architectural perspective. Analyzes existing codebase patterns
|
||||||
|
and provides implementation guidance. Use when refining issues, adding architectural
|
||||||
|
context, or when user says /arch-refine-issue.
|
||||||
model: opus
|
model: opus
|
||||||
argument-hint: <issue-number>
|
argument-hint: <issue-number>
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Architecturally Refine Issue #$1
|
# Architecturally Refine Issue #$1
|
||||||
@@ -1,8 +1,13 @@
|
|||||||
---
|
---
|
||||||
description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
|
name: arch-review-repo
|
||||||
|
description: >
|
||||||
|
Perform a full architecture review of the current repository. Analyzes structure,
|
||||||
|
patterns, dependencies, and generates prioritized recommendations. Use when reviewing
|
||||||
|
architecture, auditing codebase, or when user says /arch-review-repo.
|
||||||
model: opus
|
model: opus
|
||||||
argument-hint:
|
argument-hint:
|
||||||
context: fork
|
context: fork
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Architecture Review
|
# Architecture Review
|
||||||
@@ -2,23 +2,23 @@
|
|||||||
name: capability-writing
|
name: capability-writing
|
||||||
description: >
|
description: >
|
||||||
Guide for designing and creating capabilities for the architecture repository.
|
Guide for designing and creating capabilities for the architecture repository.
|
||||||
A capability is a cohesive set of components (skill + command + agent).
|
A capability is a cohesive set of components (skill + agent).
|
||||||
Use when creating new skills, commands, or agents, or when extending the
|
Use when creating new skills, agents, or extending the
|
||||||
AI workflow system. Includes templates, design guidance, and conventions.
|
AI workflow system. Includes templates, design guidance, and conventions.
|
||||||
user-invocable: false
|
user-invocable: false
|
||||||
---
|
---
|
||||||
|
|
||||||
# Capability Writing
|
# 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.
|
How to design and create capabilities for the architecture repository. A capability may be a single component or a cohesive set (skill + agent).
|
||||||
|
|
||||||
## Component Overview
|
## Component Overview
|
||||||
|
|
||||||
| Component | Location | Purpose | Example |
|
| Component | Location | Purpose | Example |
|
||||||
|-----------|----------|---------|---------|
|
|-----------|----------|---------|---------|
|
||||||
| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
|
| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard |
|
||||||
| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
|
| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing |
|
||||||
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |
|
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer |
|
||||||
|
|
||||||
## When to Use Each Component
|
## When to Use Each Component
|
||||||
|
|
||||||
@@ -28,36 +28,36 @@ How to design and create capabilities for the architecture repository. A capabil
|
|||||||
Start here: What do you need?
|
Start here: What do you need?
|
||||||
|
|
|
|
||||||
+--> Just knowledge to apply automatically?
|
+--> Just knowledge to apply automatically?
|
||||||
| --> Skill only
|
| --> Background skill (user-invocable: false)
|
||||||
|
|
|
|
||||||
+--> User-initiated workflow using existing knowledge?
|
+--> User-initiated workflow?
|
||||||
| --> Command (reference skills via @)
|
| --> User-invocable skill (user-invocable: true)
|
||||||
|
|
|
|
||||||
+--> Complex isolated work needing focused context?
|
+--> Complex isolated work needing focused context?
|
||||||
| --> Command + Agent (agent uses skills)
|
| --> User-invocable skill + Agent
|
||||||
|
|
|
|
||||||
+--> New domain expertise + workflow + isolated work?
|
+--> New domain expertise + workflow + isolated work?
|
||||||
--> Full capability (all three)
|
--> Full capability (background skill + user-invocable skill + agent)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Decision Matrix
|
### Decision Matrix
|
||||||
|
|
||||||
| Need | Component | Example |
|
| Need | Component | Example |
|
||||||
|------|-----------|---------|
|
|------|-----------|---------|
|
||||||
| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
|
| Knowledge Claude applies automatically | Background skill | gitea, issue-writing |
|
||||||
| User-invoked workflow | Command | /work-issue, /dashboard |
|
| User-invoked workflow | User-invocable skill | /work-issue, /dashboard |
|
||||||
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
|
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
|
||||||
| All three working together | Full capability | arch-review (skill + command + agent) |
|
| All three working together | Full capability | architecture review |
|
||||||
|
|
||||||
### Signs You Need Each Component
|
### Signs You Need Each Component
|
||||||
|
|
||||||
**Create a Skill when:**
|
**Create a Background Skill when:**
|
||||||
- You explain the same concepts repeatedly
|
- You explain the same concepts repeatedly
|
||||||
- Quality is inconsistent without explicit guidance
|
- Quality is inconsistent without explicit guidance
|
||||||
- Multiple commands need the same knowledge
|
- Multiple user-invocable skills need the same knowledge
|
||||||
- There is a clear domain that does not fit existing skills
|
- There is a clear domain that doesn't fit existing skills
|
||||||
|
|
||||||
**Create a Command when:**
|
**Create a User-Invocable Skill when:**
|
||||||
- Same workflow is used multiple times
|
- Same workflow is used multiple times
|
||||||
- User explicitly triggers the action
|
- User explicitly triggers the action
|
||||||
- Approval checkpoints are needed
|
- Approval checkpoints are needed
|
||||||
@@ -71,7 +71,47 @@ Start here: What do you need?
|
|||||||
|
|
||||||
## Component Templates
|
## Component Templates
|
||||||
|
|
||||||
### Skill Template
|
### User-Invocable Skill Template
|
||||||
|
|
||||||
|
Location: `skills/<name>/SKILL.md`
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
**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` | Yes | Set `true` for user-triggered workflows |
|
||||||
|
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
|
||||||
|
| `model` | No | `haiku`, `sonnet`, `opus` |
|
||||||
|
| `context` | No | Use `fork` for isolated context |
|
||||||
|
| `allowed-tools` | No | Restrict available tools |
|
||||||
|
|
||||||
|
### Background Skill Template
|
||||||
|
|
||||||
Location: `skills/<name>/SKILL.md`
|
Location: `skills/<name>/SKILL.md`
|
||||||
|
|
||||||
@@ -80,8 +120,7 @@ Location: `skills/<name>/SKILL.md`
|
|||||||
name: skill-name
|
name: skill-name
|
||||||
description: >
|
description: >
|
||||||
What this skill teaches and when to use it.
|
What this skill teaches and when to use it.
|
||||||
Include trigger conditions in description (not body).
|
Include trigger conditions in description.
|
||||||
List specific capabilities users would mention.
|
|
||||||
user-invocable: false
|
user-invocable: false
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -114,49 +153,6 @@ Document pitfalls to avoid.
|
|||||||
Quick-reference tables, checklists, or commands.
|
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: haiku
|
|
||||||
---
|
|
||||||
|
|
||||||
# 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
|
### Agent Template
|
||||||
|
|
||||||
Location: `agents/<name>/AGENT.md`
|
Location: `agents/<name>/AGENT.md`
|
||||||
@@ -165,7 +161,7 @@ Location: `agents/<name>/AGENT.md`
|
|||||||
---
|
---
|
||||||
name: agent-name
|
name: agent-name
|
||||||
description: What this agent does and when to spawn it
|
description: What this agent does and when to spawn it
|
||||||
model: haiku
|
model: sonnet
|
||||||
skills: skill1, skill2
|
skills: skill1, skill2
|
||||||
disallowedTools:
|
disallowedTools:
|
||||||
- Edit
|
- Edit
|
||||||
@@ -210,13 +206,13 @@ Describe expected output structure.
|
|||||||
| Model | Use When | Examples |
|
| Model | Use When | Examples |
|
||||||
|-------|----------|----------|
|
|-------|----------|----------|
|
||||||
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
|
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
|
||||||
| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer |
|
| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
|
||||||
| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor |
|
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
|
||||||
|
|
||||||
### Decision Criteria
|
### Decision Criteria
|
||||||
|
|
||||||
- **Start with `sonnet`** - handles most tasks well
|
- **Start with `haiku`** for simple display/fetch workflows
|
||||||
- **Use `haiku` for volume** - speed and cost matter at scale
|
- **Use `sonnet`** for most skills and agents (default choice)
|
||||||
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
|
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
|
||||||
- **Consider the stakes** - higher consequence tasks warrant more capable models
|
- **Consider the stakes** - higher consequence tasks warrant more capable models
|
||||||
|
|
||||||
@@ -226,31 +222,26 @@ Describe expected output structure.
|
|||||||
|
|
||||||
| Component | Convention | Examples |
|
| Component | Convention | Examples |
|
||||||
|-----------|------------|----------|
|
|-----------|------------|----------|
|
||||||
| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
|
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
|
||||||
| Skill file | UPPERCASE | `SKILL.md` |
|
| Skill file | UPPERCASE | `SKILL.md` |
|
||||||
| Command file | kebab-case | `work-issue.md`, `review-pr.md` |
|
|
||||||
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
|
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
|
||||||
| Agent file | UPPERCASE | `AGENT.md` |
|
| Agent file | UPPERCASE | `AGENT.md` |
|
||||||
|
|
||||||
### Naming Patterns
|
### Naming Patterns
|
||||||
|
|
||||||
**Skills:** Name after the domain or knowledge area
|
**Skills:** Name after the domain, knowledge area, or action
|
||||||
- Good: `gitea`, `issue-writing`, `software-architecture`
|
- Good: `gitea`, `issue-writing`, `work-issue`, `dashboard`
|
||||||
- Bad: `utils`, `helpers`, `misc`
|
- 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)
|
**Agents:** Name by role or persona (recognizable specialist)
|
||||||
- Good: `code-reviewer`, `issue-worker`, `software-architect`
|
- Good: `code-reviewer`, `issue-worker`, `software-architect`
|
||||||
- Bad: `helper`, `do-stuff`, `agent1`
|
- Bad: `helper`, `do-stuff`, `agent1`
|
||||||
|
|
||||||
## Referencing Skills
|
## Referencing Skills
|
||||||
|
|
||||||
### In Commands
|
### In User-Invocable Skills
|
||||||
|
|
||||||
Use the `@` file reference syntax to guarantee skill content is loaded:
|
Use the `@` file reference syntax to guarantee background skill content is loaded:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
@~/.claude/skills/gitea/SKILL.md
|
||||||
@@ -274,7 +265,7 @@ The agent runtime loads these skills automatically.
|
|||||||
|
|
||||||
## Common Patterns
|
## Common Patterns
|
||||||
|
|
||||||
### Approval Workflow (Commands)
|
### Approval Workflow (User-Invocable Skills)
|
||||||
|
|
||||||
Always ask before significant actions:
|
Always ask before significant actions:
|
||||||
|
|
||||||
@@ -284,7 +275,7 @@ Always ask before significant actions:
|
|||||||
6. **Present summary** with links
|
6. **Present summary** with links
|
||||||
```
|
```
|
||||||
|
|
||||||
### Conditional Behavior (Commands)
|
### Conditional Behavior (User-Invocable Skills)
|
||||||
|
|
||||||
Handle optional arguments with mode switching:
|
Handle optional arguments with mode switching:
|
||||||
|
|
||||||
@@ -298,7 +289,7 @@ Handle optional arguments with mode switching:
|
|||||||
2. Process each
|
2. Process each
|
||||||
```
|
```
|
||||||
|
|
||||||
### Spawning Agents from Commands
|
### Spawning Agents from Skills
|
||||||
|
|
||||||
Delegate complex subtasks:
|
Delegate complex subtasks:
|
||||||
|
|
||||||
@@ -323,7 +314,7 @@ disallowedTools:
|
|||||||
|
|
||||||
### Overly Broad Components
|
### Overly Broad Components
|
||||||
|
|
||||||
**Bad:** One skill/command/agent that does everything
|
**Bad:** One skill/agent that does everything
|
||||||
```markdown
|
```markdown
|
||||||
# Project Management
|
# Project Management
|
||||||
Handles issues, PRs, releases, documentation, deployment...
|
Handles issues, PRs, releases, documentation, deployment...
|
||||||
@@ -383,37 +374,32 @@ Use `tea issues create --title "..." --description "..."`
|
|||||||
|
|
||||||
## Detailed Documentation
|
## Detailed Documentation
|
||||||
|
|
||||||
For comprehensive guides, see the `docs/` directory:
|
For comprehensive guides, see:
|
||||||
|
|
||||||
- `docs/writing-skills.md` - Complete skill writing guide
|
- `docs/writing-capabilities.md` - Complete guide covering skills and agents
|
||||||
- `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
|
## Checklists
|
||||||
|
|
||||||
### Before Creating a Skill
|
### Before Creating a User-Invocable Skill
|
||||||
|
|
||||||
|
- [ ] Workflow is used multiple times
|
||||||
|
- [ ] User explicitly triggers it (not automatic)
|
||||||
|
- [ ] Clear start and end points
|
||||||
|
- [ ] Frontmatter has `user-invocable: true`
|
||||||
|
- [ ] Description includes "Use when... or when user says /skill-name"
|
||||||
|
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
||||||
|
- [ ] Approval checkpoints before significant actions
|
||||||
|
- [ ] File at `skills/<name>/SKILL.md`
|
||||||
|
|
||||||
|
### Before Creating a Background Skill
|
||||||
|
|
||||||
- [ ] Knowledge is used in multiple places (not just once)
|
- [ ] Knowledge is used in multiple places (not just once)
|
||||||
- [ ] Existing skills do not already cover this domain
|
- [ ] Existing skills do not already cover this domain
|
||||||
- [ ] Content is specific and actionable (not generic)
|
- [ ] Content is specific and actionable (not generic)
|
||||||
- [ ] Frontmatter has descriptive `description` with trigger terms
|
- [ ] Frontmatter has `user-invocable: false`
|
||||||
|
- [ ] Description includes trigger terms
|
||||||
- [ ] File at `skills/<name>/SKILL.md`
|
- [ ] 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
|
### Before Creating an Agent
|
||||||
|
|
||||||
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
||||||
|
|||||||
@@ -1,6 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Create a commit with an auto-generated conventional commit message. Analyzes staged changes and proposes a message for approval.
|
name: commit
|
||||||
|
description: >
|
||||||
|
Create a commit with an auto-generated conventional commit message. Analyzes staged
|
||||||
|
changes and proposes a message for approval. Use when committing changes, creating
|
||||||
|
commits, or when user says /commit.
|
||||||
|
model: haiku
|
||||||
argument-hint:
|
argument-hint:
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Commit Changes
|
# Commit Changes
|
||||||
@@ -1,13 +1,19 @@
|
|||||||
---
|
---
|
||||||
description: Create a new capability (skill, command, agent, or a cohesive set) for the architecture repository.
|
name: create-capability
|
||||||
|
description: >
|
||||||
|
Create a new capability (skill, agent, or a cohesive set) for the architecture
|
||||||
|
repository. Use when creating new skills, agents, extending AI workflows, or when
|
||||||
|
user says /create-capability.
|
||||||
|
model: haiku
|
||||||
argument-hint: <description>
|
argument-hint: <description>
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Capability
|
# Create Capability
|
||||||
|
|
||||||
@~/.claude/skills/capability-writing/SKILL.md
|
@~/.claude/skills/capability-writing/SKILL.md
|
||||||
|
|
||||||
Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + command + agent).
|
Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + agent).
|
||||||
|
|
||||||
## Process
|
## Process
|
||||||
|
|
||||||
@@ -20,10 +26,9 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
|
|
||||||
| Pattern | When to Use |
|
| Pattern | When to Use |
|
||||||
|---------|-------------|
|
|---------|-------------|
|
||||||
| Skill only | Knowledge to apply automatically (reused across commands) |
|
| Skill only (background) | Knowledge to apply automatically (reused across other skills) |
|
||||||
| Command only | User-invoked workflow using existing skills |
|
| Skill only (user-invocable) | User-invoked workflow |
|
||||||
| Command + Skill | New knowledge + workflow to use it |
|
| Skill + Agent | Workflow with isolated worker for complex subtasks |
|
||||||
| Command + Agent | Workflow with isolated worker for complex subtasks |
|
|
||||||
| Full set | New domain expertise + workflow + isolated work |
|
| Full set | New domain expertise + workflow + isolated work |
|
||||||
|
|
||||||
Present recommendation with reasoning:
|
Present recommendation with reasoning:
|
||||||
@@ -32,7 +37,6 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
|
|
||||||
Based on your description, I recommend:
|
Based on your description, I recommend:
|
||||||
- **Skill**: `name` - [why this knowledge is needed]
|
- **Skill**: `name` - [why this knowledge is needed]
|
||||||
- **Command**: `/name` - [what user action this enables]
|
|
||||||
- **Agent**: `name` - [why isolation/specialization is needed] (optional)
|
- **Agent**: `name` - [why isolation/specialization is needed] (optional)
|
||||||
|
|
||||||
Reasoning: [explain why this combination fits the need]
|
Reasoning: [explain why this combination fits the need]
|
||||||
@@ -48,12 +52,7 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
- What domain/knowledge does this cover?
|
- What domain/knowledge does this cover?
|
||||||
- What are the key concepts to teach?
|
- What are the key concepts to teach?
|
||||||
- What patterns or templates should it include?
|
- What patterns or templates should it include?
|
||||||
|
- Is it user-invocable (workflow) or background (reference)?
|
||||||
**For Commands:**
|
|
||||||
- What triggers this workflow?
|
|
||||||
- What are the key steps?
|
|
||||||
- What approval points are needed?
|
|
||||||
- What skills should it reference?
|
|
||||||
|
|
||||||
**For Agents:**
|
**For Agents:**
|
||||||
- What specialized role does this fill?
|
- What specialized role does this fill?
|
||||||
@@ -64,8 +63,8 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
|
|
||||||
| Model | Use For |
|
| Model | Use For |
|
||||||
|-------|---------|
|
|-------|---------|
|
||||||
| `haiku` | Simple fetch/display commands, formatting tasks |
|
| `haiku` | Simple fetch/display skills, formatting tasks |
|
||||||
| `sonnet` | Most commands and agents (default) |
|
| `sonnet` | Most skills and agents (default) |
|
||||||
| `opus` | Deep reasoning, architectural analysis, complex judgment |
|
| `opus` | Deep reasoning, architectural analysis, complex judgment |
|
||||||
|
|
||||||
For each component, recommend a model with reasoning.
|
For each component, recommend a model with reasoning.
|
||||||
@@ -73,9 +72,9 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
5. **Generate files**: Create content using templates from capability-writing skill
|
5. **Generate files**: Create content using templates from capability-writing skill
|
||||||
|
|
||||||
Ensure proper inter-references:
|
Ensure proper inter-references:
|
||||||
- Command references skill via `@~/.claude/skills/name/SKILL.md`
|
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
|
||||||
- Agent lists skills in `skills:` frontmatter (names only, not paths)
|
- Agent lists skills in `skills:` frontmatter (names only, not paths)
|
||||||
- Command spawns agent via Task tool if agent is part of the set
|
- User-invocable skill spawns agent via Task tool if agent is part of the set
|
||||||
|
|
||||||
6. **Present for approval**: Show all generated files with their full content:
|
6. **Present for approval**: Show all generated files with their full content:
|
||||||
```
|
```
|
||||||
@@ -84,9 +83,6 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
### skills/name/SKILL.md
|
### skills/name/SKILL.md
|
||||||
[full content]
|
[full content]
|
||||||
|
|
||||||
### commands/name.md
|
|
||||||
[full content]
|
|
||||||
|
|
||||||
### agents/name/AGENT.md (if applicable)
|
### agents/name/AGENT.md (if applicable)
|
||||||
[full content]
|
[full content]
|
||||||
|
|
||||||
@@ -95,7 +91,6 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
|
|
||||||
7. **Create files** in correct locations after approval:
|
7. **Create files** in correct locations after approval:
|
||||||
- `skills/<name>/SKILL.md`
|
- `skills/<name>/SKILL.md`
|
||||||
- `commands/<name>.md`
|
|
||||||
- `agents/<name>/AGENT.md`
|
- `agents/<name>/AGENT.md`
|
||||||
|
|
||||||
8. **Report success**:
|
8. **Report success**:
|
||||||
@@ -104,13 +99,12 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
|
|
||||||
Files created:
|
Files created:
|
||||||
- skills/name/SKILL.md
|
- skills/name/SKILL.md
|
||||||
- commands/name.md
|
|
||||||
- agents/name/AGENT.md (if applicable)
|
- agents/name/AGENT.md (if applicable)
|
||||||
|
|
||||||
Next steps:
|
Next steps:
|
||||||
1. Run `make install` to symlink to ~/.claude/
|
1. Run `make install` to symlink to ~/.claude/
|
||||||
2. Test with: /name (for commands)
|
2. Test with: /name (for user-invocable skills)
|
||||||
3. Skills will auto-activate based on context
|
3. Background skills will auto-activate based on context
|
||||||
```
|
```
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
@@ -118,6 +112,6 @@ Create new capabilities following established patterns. A capability may be a si
|
|||||||
- Follow all conventions from capability-writing skill
|
- Follow all conventions from capability-writing skill
|
||||||
- Reference existing skills rather than duplicating knowledge
|
- Reference existing skills rather than duplicating knowledge
|
||||||
- Keep components focused - split if scope is too broad
|
- Keep components focused - split if scope is too broad
|
||||||
- Commands should have approval checkpoints before significant actions
|
- User-invocable skills should have approval checkpoints before significant actions
|
||||||
- Default to `sonnet` model unless there's a clear reason for haiku/opus
|
- Default to `sonnet` model unless there's a clear reason for haiku/opus
|
||||||
- Skills should have descriptive `description` fields for auto-activation
|
- Skills should have descriptive `description` fields for auto-activation
|
||||||
@@ -1,7 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: Create a new Gitea issue. Can create single issues or batch create from a plan.
|
name: create-issue
|
||||||
|
description: >
|
||||||
|
Create a new Gitea issue. Can create single issues or batch create from a plan.
|
||||||
|
Use when creating issues, adding tickets, or when user says /create-issue.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint: [title] or "batch"
|
argument-hint: [title] or "batch"
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Issue(s)
|
# Create Issue(s)
|
||||||
@@ -1,8 +1,13 @@
|
|||||||
---
|
---
|
||||||
description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
|
name: create-repo
|
||||||
|
description: >
|
||||||
|
Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md,
|
||||||
|
and CI configuration. Use when creating repos, initializing projects, or when user
|
||||||
|
says /create-repo.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint: <repo-name>
|
argument-hint: <repo-name>
|
||||||
context: fork
|
context: fork
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Repository
|
# Create Repository
|
||||||
@@ -155,7 +160,7 @@ Create a new repository with Flowmade's standard structure.
|
|||||||
- CI workflow template
|
- CI workflow template
|
||||||
- Basic Makefile
|
- Basic Makefile
|
||||||
|
|
||||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
Generated with [Claude Code](https://claude.com/claude-code)
|
||||||
|
|
||||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||||
|
|
||||||
@@ -1,8 +1,10 @@
|
|||||||
---
|
---
|
||||||
description: Show dashboard of open issues, PRs awaiting review, and CI status.
|
name: dashboard
|
||||||
# Model: haiku is sufficient for fetching and displaying data.
|
description: >
|
||||||
# This command only reads from Gitea and formats output - no complex reasoning needed.
|
Show dashboard of open issues, PRs awaiting review, and CI status. Use when
|
||||||
|
checking project status, viewing issues/PRs, or when user says /dashboard.
|
||||||
model: haiku
|
model: haiku
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Repository Dashboard
|
# Repository Dashboard
|
||||||
@@ -55,7 +57,7 @@ Run `tea actions runs` to list recent workflow runs.
|
|||||||
|
|
||||||
Present each section with a clear header. Example:
|
Present each section with a clear header. Example:
|
||||||
|
|
||||||
\`\`\`
|
```
|
||||||
## Open Issues (3)
|
## Open Issues (3)
|
||||||
|
|
||||||
| # | Title | Author |
|
| # | Title | Author |
|
||||||
@@ -78,11 +80,11 @@ Present each section with a clear header. Example:
|
|||||||
| **[FAILURE]** | build | PR #16 | abc1234 | 2h ago |
|
| **[FAILURE]** | build | PR #16 | abc1234 | 2h ago |
|
||||||
| [SUCCESS] | build | main | def5678 | 5h ago |
|
| [SUCCESS] | build | main | def5678 | 5h ago |
|
||||||
| [SUCCESS] | lint | main | def5678 | 5h ago |
|
| [SUCCESS] | lint | main | def5678 | 5h ago |
|
||||||
\`\`\`
|
```
|
||||||
|
|
||||||
If no CI is configured:
|
If no CI is configured:
|
||||||
\`\`\`
|
```
|
||||||
## CI Status
|
## CI Status
|
||||||
|
|
||||||
No CI workflows configured for this repository.
|
No CI workflows configured for this repository.
|
||||||
\`\`\`
|
```
|
||||||
@@ -1,7 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
|
name: groom
|
||||||
|
description: >
|
||||||
|
Groom and improve issues. Without argument, reviews all open issues. With argument,
|
||||||
|
grooms specific issue. Use when grooming backlog, improving issues, or when user
|
||||||
|
says /groom.
|
||||||
model: sonnet
|
model: sonnet
|
||||||
argument-hint: [issue-number]
|
argument-hint: [issue-number]
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Groom Issues
|
# Groom Issues
|
||||||
@@ -1,8 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
|
name: improve
|
||||||
|
description: >
|
||||||
|
Identify improvement opportunities based on product vision. Analyzes gaps between
|
||||||
|
vision goals and current backlog. Use when analyzing alignment, finding gaps, or
|
||||||
|
when user says /improve.
|
||||||
model: sonnet
|
model: sonnet
|
||||||
argument-hint:
|
|
||||||
context: fork
|
context: fork
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Improvement Analysis
|
# Improvement Analysis
|
||||||
@@ -1,7 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
|
name: manifesto
|
||||||
|
description: >
|
||||||
|
View and manage the organization manifesto. Shows identity, personas, beliefs,
|
||||||
|
and principles. Use when viewing manifesto, checking organization identity, or
|
||||||
|
when user says /manifesto.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint:
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Organization Manifesto
|
# Organization Manifesto
|
||||||
@@ -1,8 +1,13 @@
|
|||||||
---
|
---
|
||||||
description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
|
name: plan-issues
|
||||||
|
description: >
|
||||||
|
Plan and create issues for a feature or improvement. Breaks down work into
|
||||||
|
well-structured issues with vision alignment. Use when planning a feature,
|
||||||
|
creating a roadmap, breaking down large tasks, or when user says /plan-issues.
|
||||||
model: sonnet
|
model: sonnet
|
||||||
argument-hint: <feature-description>
|
argument-hint: <feature-description>
|
||||||
context: fork
|
context: fork
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Plan Feature: $1
|
# Plan Feature: $1
|
||||||
@@ -25,7 +30,7 @@ context: fork
|
|||||||
- What exists today?
|
- What exists today?
|
||||||
- Where does the workflow break or have gaps?
|
- Where does the workflow break or have gaps?
|
||||||
- What's the MVP that delivers value?
|
- What's the MVP that delivers value?
|
||||||
|
|
||||||
Present this as a workflow walkthrough before proposing any issues.
|
Present this as a workflow walkthrough before proposing any issues.
|
||||||
|
|
||||||
7. **Break down** into discrete, actionable issues:
|
7. **Break down** into discrete, actionable issues:
|
||||||
@@ -1,5 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: Create a PR from current branch. Auto-generates title and description from branch name and commits.
|
name: pr
|
||||||
|
description: >
|
||||||
|
Create a PR from current branch. Auto-generates title and description from branch
|
||||||
|
name and commits. Use when creating pull requests, submitting changes, or when
|
||||||
|
user says /pr.
|
||||||
|
model: haiku
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Pull Request
|
# Create Pull Request
|
||||||
@@ -17,8 +17,7 @@ All product repos should follow this structure relative to the architecture repo
|
|||||||
org/
|
org/
|
||||||
├── architecture/ # Organizational source of truth
|
├── architecture/ # Organizational source of truth
|
||||||
│ ├── manifesto.md # Organization identity and beliefs
|
│ ├── manifesto.md # Organization identity and beliefs
|
||||||
│ ├── commands/ # Claude Code workflows
|
│ ├── skills/ # User-invocable and background skills
|
||||||
│ ├── skills/ # Knowledge modules
|
|
||||||
│ └── agents/ # Subtask handlers
|
│ └── agents/ # Subtask handlers
|
||||||
├── product-a/ # Product repository
|
├── product-a/ # Product repository
|
||||||
│ ├── vision.md # Product vision (extends manifesto)
|
│ ├── vision.md # Product vision (extends manifesto)
|
||||||
|
|||||||
@@ -1,12 +1,17 @@
|
|||||||
---
|
---
|
||||||
description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
|
name: retro
|
||||||
|
description: >
|
||||||
|
Run a retrospective on completed work. Captures insights as issues for later
|
||||||
|
encoding into skills/agents. Use when capturing learnings, running retrospectives,
|
||||||
|
or when user says /retro.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint: [task-description]
|
argument-hint: [task-description]
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Retrospective
|
# Retrospective
|
||||||
|
|
||||||
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/commands/agents.
|
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/agents.
|
||||||
|
|
||||||
@~/.claude/skills/vision-management/SKILL.md
|
@~/.claude/skills/vision-management/SKILL.md
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
@~/.claude/skills/gitea/SKILL.md
|
||||||
@@ -14,7 +19,7 @@ Capture insights from completed work as issues on the architecture repo. Issues
|
|||||||
## Flow
|
## Flow
|
||||||
|
|
||||||
```
|
```
|
||||||
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/command/agent
|
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/agent
|
||||||
```
|
```
|
||||||
|
|
||||||
The retro creates the issue. Encoding happens when the issue is worked on.
|
The retro creates the issue. Encoding happens when the issue is worked on.
|
||||||
@@ -30,7 +35,7 @@ The retro creates the issue. Encoding happens when the issue is worked on.
|
|||||||
|
|
||||||
3. **Identify insights**: For each insight, determine:
|
3. **Identify insights**: For each insight, determine:
|
||||||
- **What was learned**: The specific insight
|
- **What was learned**: The specific insight
|
||||||
- **Where to encode it**: Which skill, command, or agent should change?
|
- **Where to encode it**: Which skill or agent should change?
|
||||||
- **Governance impact**: What does this mean for how we work?
|
- **Governance impact**: What does this mean for how we work?
|
||||||
|
|
||||||
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
|
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
|
||||||
@@ -46,7 +51,6 @@ The retro creates the issue. Encoding happens when the issue is worked on.
|
|||||||
|
|
||||||
## Suggested Encoding
|
## Suggested Encoding
|
||||||
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
|
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
|
||||||
- [ ] \`commands/xxx.md\` - [what to add/change]
|
|
||||||
- [ ] \`agents/xxx/agent.md\` - [what to add/change]
|
- [ ] \`agents/xxx/agent.md\` - [what to add/change]
|
||||||
|
|
||||||
## Governance
|
## Governance
|
||||||
@@ -79,14 +83,13 @@ When encoding a learning issue, the implementer should:
|
|||||||
## Encoded In
|
## Encoded In
|
||||||
|
|
||||||
- `skills/xxx/SKILL.md` - [what was added/changed]
|
- `skills/xxx/SKILL.md` - [what was added/changed]
|
||||||
- `commands/xxx.md` - [what was added/changed]
|
|
||||||
|
|
||||||
## Governance
|
## Governance
|
||||||
|
|
||||||
[What this means for how we work]
|
[What this means for how we work]
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Update skill/command/agent** with the encoded knowledge
|
2. **Update skill/agent** with the encoded knowledge
|
||||||
|
|
||||||
3. **Close the issue** with reference to the learning file and changes made
|
3. **Close the issue** with reference to the learning file and changes made
|
||||||
|
|
||||||
@@ -95,7 +98,7 @@ When encoding a learning issue, the implementer should:
|
|||||||
| Insight Type | Encode In |
|
| Insight Type | Encode In |
|
||||||
|--------------|-----------|
|
|--------------|-----------|
|
||||||
| How to use a tool | `skills/[tool]/SKILL.md` |
|
| How to use a tool | `skills/[tool]/SKILL.md` |
|
||||||
| Workflow improvement | `commands/[command].md` |
|
| Workflow improvement | `skills/[skill]/SKILL.md` (user-invocable) |
|
||||||
| Subtask behavior | `agents/[agent]/agent.md` |
|
| Subtask behavior | `agents/[agent]/agent.md` |
|
||||||
| Organization belief | `manifesto.md` |
|
| Organization belief | `manifesto.md` |
|
||||||
| Product direction | `vision.md` (in product repo) |
|
| Product direction | `vision.md` (in product repo) |
|
||||||
@@ -104,8 +107,8 @@ When encoding a learning issue, the implementer should:
|
|||||||
|
|
||||||
Add appropriate labels to issues:
|
Add appropriate labels to issues:
|
||||||
- `learning` - Always add this
|
- `learning` - Always add this
|
||||||
- `prompt-improvement` - For command/skill text changes
|
- `prompt-improvement` - For skill text changes
|
||||||
- `new-feature` - For new commands/skills/agents
|
- `new-feature` - For new skills/agents
|
||||||
- `bug` - For things that are broken
|
- `bug` - For things that are broken
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
@@ -1,7 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Review a Gitea pull request. Fetches PR details, diff, and comments. Includes both code review and software architecture review.
|
name: review-pr
|
||||||
|
description: >
|
||||||
|
Review a Gitea pull request. Fetches PR details, diff, and comments. Includes
|
||||||
|
both code review and software architecture review. Use when reviewing pull requests,
|
||||||
|
checking code quality, or when user says /review-pr.
|
||||||
model: sonnet
|
model: sonnet
|
||||||
argument-hint: <pr-number>
|
argument-hint: <pr-number>
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Review PR #$1
|
# Review PR #$1
|
||||||
@@ -1,10 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
|
name: roadmap
|
||||||
# Model: haiku is sufficient for fetching and organizing issue data.
|
description: >
|
||||||
# This command reads issues and dependencies, then displays them in categories.
|
View current issues as a roadmap. Shows open issues organized by status and
|
||||||
# Basic categorization logic doesn't require advanced reasoning.
|
dependencies. Use when viewing roadmap, checking issue status, or when user
|
||||||
|
says /roadmap.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint:
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Roadmap View
|
# Roadmap View
|
||||||
@@ -1,8 +1,10 @@
|
|||||||
---
|
---
|
||||||
allowed-tools: Bash, Task, Read, TaskOutput
|
name: spawn-issues
|
||||||
model: haiku
|
|
||||||
description: Orchestrate parallel issue implementation with review cycles
|
description: Orchestrate parallel issue implementation with review cycles
|
||||||
|
model: haiku
|
||||||
argument-hint: <issue-number> [<issue-number>...]
|
argument-hint: <issue-number> [<issue-number>...]
|
||||||
|
allowed-tools: Bash, Task, Read, TaskOutput
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Spawn Issues (Orchestrator)
|
# Spawn Issues (Orchestrator)
|
||||||
@@ -1,8 +1,10 @@
|
|||||||
---
|
---
|
||||||
allowed-tools: Bash, Task, Read
|
name: spawn-pr-fixes
|
||||||
model: haiku
|
|
||||||
description: Spawn parallel background agents to address PR review feedback
|
description: Spawn parallel background agents to address PR review feedback
|
||||||
|
model: haiku
|
||||||
argument-hint: [pr-number...]
|
argument-hint: [pr-number...]
|
||||||
|
allowed-tools: Bash, Task, Read
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Spawn PR Fixes
|
# Spawn PR Fixes
|
||||||
@@ -1,8 +1,12 @@
|
|||||||
---
|
---
|
||||||
description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
|
name: update-claude-md
|
||||||
|
description: >
|
||||||
|
Update or create CLAUDE.md with current project context. Explores the project
|
||||||
|
and ensures organization context is present. Use when updating project docs,
|
||||||
|
adding CLAUDE.md, or when user says /update-claude-md.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint:
|
|
||||||
context: fork
|
context: fork
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Update CLAUDE.md
|
# Update CLAUDE.md
|
||||||
@@ -1,7 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
|
name: vision
|
||||||
|
description: >
|
||||||
|
View the product vision and goal progress. Manages vision.md and Gitea milestones.
|
||||||
|
Use when viewing vision, managing goals, or when user says /vision.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint: [goals]
|
argument-hint: [goals]
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Product Vision
|
# Product Vision
|
||||||
@@ -9,12 +13,12 @@ argument-hint: [goals]
|
|||||||
@~/.claude/skills/vision-management/SKILL.md
|
@~/.claude/skills/vision-management/SKILL.md
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
@~/.claude/skills/gitea/SKILL.md
|
||||||
|
|
||||||
This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
This skill manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
| Level | Document | Purpose | Command |
|
| Level | Document | Purpose | Skill |
|
||||||
|-------|----------|---------|---------|
|
|-------|----------|---------|-------|
|
||||||
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
|
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
|
||||||
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
|
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
|
||||||
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
|
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
|
||||||
@@ -1,7 +1,11 @@
|
|||||||
---
|
---
|
||||||
description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
|
name: work-issue
|
||||||
|
description: >
|
||||||
|
Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
|
||||||
|
Use when working on issues, implementing features, or when user says /work-issue.
|
||||||
model: haiku
|
model: haiku
|
||||||
argument-hint: <issue-number>
|
argument-hint: <issue-number>
|
||||||
|
user-invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Work on Issue #$1
|
# Work on Issue #$1
|
||||||
Reference in New Issue
Block a user