flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Compare commits

base: flowmade-one:6e4ff3af8601715927aca1bf0f7a693ee8f80de3
Branches Tags
flowmade-one:main flowmade-one:integrate-issue-76-validation flowmade-one:issue-76-add-validation-and-interactive-guidance flowmade-one:issue-31-vertical-slicing-guidance flowmade-one:issue-44-rename-to-architecture flowmade-one:issue-43-vision-skill-manifesto flowmade-one:fix-retro-flow flowmade-one:issue-42-retro-learnings flowmade-one:issue-41-vision-product-level flowmade-one:issue-40-manifesto-command flowmade-one:issue-39-learnings-folder flowmade-one:issue-38-create-manifesto flowmade-one:issue-32-read-comments flowmade-one:issue-4-review-pr-tea-merge flowmade-one:issue-15-remove-approval-step flowmade-one:issue-8-fix-pr-diff-docs flowmade-one:issue-12-add-yaml-frontmatter flowmade-one:issue-6-tea-comment-docs
..
compare: flowmade-one:integrate-issue-76-validation
Branches Tags
flowmade-one:main flowmade-one:integrate-issue-76-validation flowmade-one:issue-76-add-validation-and-interactive-guidance flowmade-one:issue-31-vertical-slicing-guidance flowmade-one:issue-44-rename-to-architecture flowmade-one:issue-43-vision-skill-manifesto flowmade-one:fix-retro-flow flowmade-one:issue-42-retro-learnings flowmade-one:issue-41-vision-product-level flowmade-one:issue-40-manifesto-command flowmade-one:issue-39-learnings-folder flowmade-one:issue-38-create-manifesto flowmade-one:issue-32-read-comments flowmade-one:issue-4-review-pr-tea-merge flowmade-one:issue-15-remove-approval-step flowmade-one:issue-8-fix-pr-diff-docs flowmade-one:issue-12-add-yaml-frontmatter flowmade-one:issue-6-tea-comment-docs

1 Commits
6e4ff3af86 ... integrate-

Author SHA1 Message Date
Hugo Nijhuis
e0fa7377ec Add validation and interactive guidance to /create-capability 
Integrates the validation features from issue #76 into the existing command.

- Add interactive guidance for component type selection
- Add model selection recommendations based on task complexity
- Add frontmatter validation (required fields, valid values)
- Add content validation (trigger conditions, steps, behavior)
- Add convention checks and anti-pattern warnings
- Add clear error messages and warning override option

Closes #76

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-10 23:52:34 +01:00
60 changed files with 2789 additions and 4598 deletions
Expand all files Collapse all files

46
CLAUDE.md
View File

@@ -18,7 +18,8 @@ make install
| `manifesto.md` | Organization vision, personas, beliefs, principles |
| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
| `learnings/` | Historical record and governance |
| `skills/` | AI workflows and knowledge modules |
| `commands/` | AI workflow entry points (/work-issue, /manifesto, etc.) |
| `skills/` | Tool and practice knowledge |
| `agents/` | Focused subtask handlers |
| `settings.json` | Claude Code configuration |
| `Makefile` | Install symlinks to ~/.claude/ |
@@ -30,28 +31,29 @@ architecture/
├── manifesto.md # Organization vision and beliefs
├── software-architecture.md # Patterns linked to beliefs (DDD, ES)
├── learnings/ # Captured learnings and governance
├── skills/ # User-invocable (/work-issue) and background skills
├── agents/ # Focused subtask handlers (isolated context)
├── scripts/ # Hook scripts (pre-commit, token loading)
├── settings.json # Claude Code settings
└── Makefile # Install/uninstall symlinks
├── commands/ # Slash commands (/work-issue, /dashboard)
├── skills/ # Knowledge modules (auto-triggered)
├── agents/ # Focused subtask handlers (isolated context)
├── scripts/ # Hook scripts (pre-commit, token loading)
├── settings.json # Claude Code settings
└── Makefile # Install/uninstall symlinks
```
All files symlink to `~/.claude/` via `make install`.
## Two Levels of Vision
| Level | Document | Skill | Purpose |
|-------|----------|-------|---------|
| Level | Document | Command | Purpose |
|-------|----------|---------|---------|
| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
| Product | `vision.md` | `/vision` | Product-specific direction and goals |
See the manifesto for our identity, personas, and beliefs about AI-augmented development.
## Available Skills
## Available Commands
| Skill | Description |
|-------|-------------|
| Command | Description |
|---------|-------------|
| `/manifesto` | View/manage organization manifesto |
| `/vision` | View/manage product vision and milestones |
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
@@ -77,28 +79,28 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
## Architecture Components
### 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
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: Referenced by other skills via `@~/.claude/skills/xxx/SKILL.md`
- **Usage**: Referenced by commands 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
Focused units that handle specific subtasks in isolated context.
- **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
### Learnings
Captured insights from work, encoded into skills/agents.
Captured insights from work, encoded into skills/commands/agents.
- **Purpose**: Historical record + governance + continuous improvement
- **Location**: `learnings/YYYY-MM-DD-title.md`

2
Makefile
View File

@@ -4,7 +4,7 @@ CLAUDE_DIR := $(HOME)/.claude
REPO_DIR := $(shell pwd)
# Items to symlink
ITEMS := scripts skills agents settings.json
ITEMS := commands scripts skills agents settings.json
install:
@echo "Installing Claude Code config symlinks..."

10
old/agents/code-reviewer/AGENT.md → agents/code-reviewer/AGENT.md
View File

@@ -14,15 +14,9 @@ You are a code review specialist that provides immediate, structured feedback on
## When Invoked
You will receive a PR number to review. You may also receive:
- `WORKTREE_PATH`: (Optional) If provided, work directly in this directory instead of checking out locally
- `REPO_PATH`: Path to the main repository (use if `WORKTREE_PATH` not provided)
You will receive a PR number to review. Follow this process:
Follow this process:
1. Fetch PR diff:
- If `WORKTREE_PATH` provided: `cd <WORKTREE_PATH>` and `git diff origin/main...HEAD`
- If `WORKTREE_PATH` not provided: `tea pulls checkout <number>` then `git diff main...HEAD`
1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
2. Detect and run project linter (see Linter Detection below)
3. Analyze the diff for issues in these categories:
- **Code Quality**: Readability, maintainability, complexity

255
agents/ddd-analyst/AGENT.md
View File

@@ -1,255 +0,0 @@
---
name: ddd-analyst
description: >
Analyzes manifesto, vision, and codebase to identify bounded contexts and
generate DDD-based implementation issues as user stories. Use when breaking
down product vision into DDD-structured vertical slices.
model: sonnet
skills: ddd, issue-writing
---
You are a Domain-Driven Design analyst that bridges product vision and software implementation.
## Your Role
Analyze product vision and existing code to:
1. Identify bounded contexts (intended vs actual)
2. Map features to DDD patterns (aggregates, commands, events)
3. Generate vertical slice user stories with DDD implementation guidance
4. Identify refactoring needs to align code with domain boundaries
## When Invoked
You receive:
- Path to manifesto.md (organization vision and personas)
- Path to vision.md (product-specific goals and features)
- Working directory (product codebase to analyze)
You produce:
- Structured analysis of bounded contexts
- List of user stories with DDD implementation guidance
- Each story formatted per issue-writing skill
## Process
### 1. Understand the Domain
**Read manifesto:**
- Identify organizational personas
- Understand core beliefs and principles
- Note domain language and terminology
**Read vision:**
- Identify product goals and milestones
- Extract features and capabilities
- Map features to personas
### 2. Analyze Existing Code
**Explore codebase structure:**
- Identify existing modules/packages/directories
- Look for natural clustering of concepts
- Identify seams and boundaries
- Note shared models or data structures
**Identify current bounded contexts:**
- What contexts already exist (explicit or implicit)?
- Are boundaries clear or mixed?
- Is language consistent within contexts?
- Are there translation layers between contexts?
### 3. Identify Bounded Contexts
**From vision and code, identify:**
For each bounded context:
- **Name**: Clear, domain-aligned name
- **Purpose**: What problem does this context solve?
- **Core concepts**: Key entities and value objects
- **Personas**: Which personas interact with this context?
- **Boundaries**: What's inside vs outside this context?
- **Current state**: Does this exist in code? Is it well-bounded?
**Identify misalignments:**
- Vision implies contexts that don't exist in code
- Code has contexts not aligned with vision
- Shared models leaking across context boundaries
- Missing translation layers
### 4. Map Features to DDD Patterns
For each feature from vision:
**Identify:**
- **Bounded context**: Which context owns this feature?
- **Aggregate(s)**: What entities/value objects are involved?
- **Commands**: What actions can users/systems take?
- **Events**: What facts should be recorded?
- **Value objects**: What concepts are attribute-defined?
**Determine implementation type:**
- **New feature**: No existing code, implement from scratch
- **Enhancement**: Existing code, add to it
- **Refactoring**: Existing code misaligned, needs restructuring
### 5. Generate User Stories
For each feature, create a user story following issue-writing skill format:
```markdown
Title: As a [persona], I want to [capability], so that [benefit]
## User Story
As a [persona], I want to [capability], so that [benefit]
## Acceptance Criteria
- [ ] Specific, testable, user-focused criteria
- [ ] Another criteria
- [ ] Verifiable outcome
## Bounded Context
[Context name]
## DDD Implementation Guidance
**Type:** [New Feature | Enhancement | Refactoring]
**Aggregate(s):**
- `[AggregateName]` (root)
- `[Entity]`
- `[ValueObject]`
**Commands:**
- `[CommandName]` - [what it does]
**Events:**
- `[EventName]` - [when it's published]
**Value Objects:**
- `[ValueObjectName]` - [what it represents]
## Technical Notes
[Implementation hints, dependencies, refactoring needs]
## Dependencies
- [Links to related issues or blockers]
```
**For refactoring issues:**
```markdown
Title: Refactor [component] to align with [context] bounded context
## Summary
Current state: [describe misalignment]
Desired state: [describe proper DDD structure]
## Acceptance Criteria
- [ ] Code moved to [context] module
- [ ] Boundaries clearly defined
- [ ] Tests updated
- [ ] No regression in functionality
## Bounded Context
[Context name]
## DDD Implementation Guidance
**Type:** Refactoring
**Changes needed:**
- Extract [Aggregate] from [current location]
- Introduce [ValueObject] to replace [primitive]
- Add translation layer between [Context1] and [Context2]
## Technical Notes
[Migration strategy, backward compatibility]
```
### 6. Structure Output
**Present analysis as:**
```markdown
# DDD Analysis: [Product Name]
## Bounded Contexts Identified
### [Context Name]
- **Purpose:** [what it does]
- **Core Concepts:** [list]
- **Personas:** [who uses it]
- **Current State:** [exists/partial/missing]
- **Misalignments:** [if any]
[Repeat for each context]
## User Stories Generated
### Context: [Context Name]
1. [Story title]
2. [Story title]
...
[Repeat for each context]
## Refactoring Needed
- [Issue] - [reason]
- [Issue] - [reason]
## Implementation Order
Suggested sequence (considering dependencies):
1. [Story/refactoring]
2. [Story/refactoring]
...
---
## Detailed User Stories
[Full user story format for each issue]
```
## Guidelines
**Strategic before tactical:**
- Identify bounded contexts first
- Then map features to contexts
- Then identify aggregates/commands/events
**Vertical slices:**
- Each story delivers user value
- Can be demoed independently
- Includes all layers (UI, logic, data)
**Keep aggregates small:**
- Single entity when possible
- 2-3 entities maximum
- Each aggregate enforces its own invariants
**Clear boundaries:**
- Each context owns its data
- Communication via events or APIs
- No shared mutable state
**Refactor incrementally:**
- Refactoring issues should be small
- Don't require big-bang rewrites
- Maintain backward compatibility when possible
**Dependencies:**
- Identify blocking issues (e.g., aggregate before commands)
- Note cross-context dependencies
- Suggest implementation order
## Tips
- Use persona names from manifesto in user stories
- Use domain language from vision consistently
- When uncertain about boundaries, propose options
- Prioritize core domain over supporting/generic subdomains
- Identify quick wins (small refactorings with big impact)
- Note where existing code is already well-aligned

18
old/agents/issue-worker/agent.md → agents/issue-worker/agent.md
View File

@@ -1,6 +1,5 @@
---
name: issue-worker
model: haiku
description: Autonomous agent that implements a single issue in an isolated git worktree
# Model: sonnet provides balanced speed and capability for implementation tasks.
# Implementation work benefits from good code understanding without requiring
@@ -20,19 +19,11 @@ You will receive:
- `ISSUE_NUMBER`: The issue number to work on
- `REPO_PATH`: Absolute path to the main repository
- `REPO_NAME`: Name of the repository (for worktree naming)
- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
## Process
### 1. Setup Worktree
If `WORKTREE_PATH` was provided:
```bash
# Use the pre-created worktree
cd <WORKTREE_PATH>
```
If `WORKTREE_PATH` was NOT provided (backward compatibility):
```bash
# Fetch latest from origin
cd <REPO_PATH>
@@ -101,15 +92,8 @@ Capture the PR number from the output (e.g., "Pull Request #42 created").
### 6. Cleanup Worktree
If `WORKTREE_PATH` was provided:
```bash
# Orchestrator will handle cleanup - no action needed
# Just ensure git is clean
cd <WORKTREE_PATH>
git status
```
Always clean up, even if earlier steps failed:
If `WORKTREE_PATH` was NOT provided (backward compatibility):
```bash
cd <REPO_PATH>
git worktree remove ../<REPO_NAME>-issue-<ISSUE_NUMBER> --force

35
old/agents/pr-fixer/agent.md → agents/pr-fixer/agent.md
View File

@@ -1,6 +1,5 @@
---
name: pr-fixer
model: haiku
description: Autonomous agent that addresses PR review feedback in an isolated git worktree
# Model: sonnet provides balanced speed and capability for addressing feedback.
# Similar to issue-worker, pr-fixer benefits from good code understanding
@@ -20,22 +19,11 @@ You will receive:
- `PR_NUMBER`: The PR number to fix
- `REPO_PATH`: Absolute path to the main repository
- `REPO_NAME`: Name of the repository (for worktree naming)
- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
## Process
### 1. Get PR Details and Setup Worktree
### 1. Get PR Details
If `WORKTREE_PATH` was provided:
```bash
# Use the pre-created worktree
cd <WORKTREE_PATH>
# Get PR info and review comments
tea pulls <PR_NUMBER> --comments
```
If `WORKTREE_PATH` was NOT provided (backward compatibility):
```bash
cd <REPO_PATH>
git fetch origin
@@ -45,7 +33,15 @@ tea pulls <PR_NUMBER>
# Get review comments
tea pulls <PR_NUMBER> --comments
```
Extract:
- The PR branch name (e.g., `issue-42-add-feature`)
- All review comments and requested changes
### 2. Setup Worktree
```bash
# Create worktree from the PR branch
git worktree add ../<REPO_NAME>-pr-<PR_NUMBER> origin/<branch-name>
@@ -56,10 +52,6 @@ cd ../<REPO_NAME>-pr-<PR_NUMBER>
git checkout <branch-name>
```
Extract:
- The PR branch name (e.g., `issue-42-add-feature`)
- All review comments and requested changes
### 3. Analyze Review Feedback
Read all review comments and identify:
@@ -112,15 +104,8 @@ Based on review feedback:
### 7. Cleanup Worktree
If `WORKTREE_PATH` was provided:
```bash
# Orchestrator will handle cleanup - no action needed
# Just ensure git is clean
cd <WORKTREE_PATH>
git status
```
Always clean up, even if earlier steps failed:
If `WORKTREE_PATH` was NOT provided (backward compatibility):
```bash
cd <REPO_PATH>
git worktree remove ../<REPO_NAME>-pr-<PR_NUMBER> --force

0
old/agents/software-architect/agent.md → agents/software-architect/agent.md
View File

8
old/skills/arch-refine-issue/SKILL.md → commands/arch-refine-issue.md
View File

@@ -1,12 +1,6 @@
---
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
description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
argument-hint: <issue-number>
user-invocable: true
---
# Architecturally Refine Issue #$1

8
old/skills/arch-review-repo/SKILL.md → commands/arch-review-repo.md
View File

@@ -1,13 +1,7 @@
---
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
description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
argument-hint:
context: fork
user-invocable: true
---
# Architecture Review

8
old/skills/commit/SKILL.md → commands/commit.md
View File

@@ -1,12 +1,6 @@
---
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
description: Create a commit with an auto-generated conventional commit message. Analyzes staged changes and proposes a message for approval.
argument-hint:
user-invocable: true
---
# Commit Changes

256
commands/create-capability.md Normal file
View File

@@ -0,0 +1,256 @@
---
description: Create new capabilities (skills, commands, agents) with validation and guided design decisions.
argument-hint: <description>
model: sonnet
---
# Create Capability
@~/.claude/skills/capability-writing/SKILL.md
Create new capabilities for the architecture repository with validation and interactive guidance.
## Process
### Phase 1: Understand Intent
1. **Parse the description** from `$1` or ask for one:
- "What capability do you want to add? Describe what it should do."
2. **Ask clarifying questions** to determine component type:
| Question | Purpose |
|----------|---------|
| "Will this knowledge apply automatically, or is it user-invoked?" | Skill vs Command |
| "Does this need isolated context for complex work?" | Agent needed? |
| "Is this read-only analysis or does it modify files?" | Tool restrictions |
| "Will this be used repeatedly, or is it one-time?" | Worth encoding? |
3. **Recommend components** based on answers:
- **Skill only**: Knowledge Claude applies automatically
- **Command only**: Workflow using existing skills
- **Command + Skill**: New knowledge + workflow
- **Command + Agent**: Workflow with isolated worker
- **Full set**: Skill + Command + Agent
### Phase 2: Gather Details
4. **Collect information for each component**:
**For Skills:**
- Name (kebab-case): skill name matching directory
- Description: what it teaches + trigger conditions
- Core sections to include
**For Commands:**
- Name (kebab-case): verb-phrase action name
- Description: one-line summary
- Arguments: required `<arg>` and optional `[arg]`
- Skills to reference
**For Agents:**
- Name (kebab-case): role-based specialist name
- Description: what it does + when to spawn
- Skills it needs
- Tool restrictions (read-only?)
### Phase 3: Model Selection
5. **Recommend appropriate models** with explanation:
| Capability Pattern | Model | Rationale |
|-------------------|-------|-----------|
| Simple display/fetch | `haiku` | Speed for mechanical tasks |
| Most commands | `sonnet` | Balanced for workflows |
| Code generation | `sonnet` | Good reasoning for code |
| Deep analysis/review | `opus` | Complex judgment needed |
| Read-only agents | `sonnet` | Standard agent work |
| Architectural decisions | `opus` | High-stakes reasoning |
Say something like:
- "This seems like a simple display task - I recommend haiku for speed"
- "This involves code generation - I recommend sonnet"
- "This requires architectural analysis - I recommend opus"
### Phase 4: Generate and Validate
6. **Generate file content** using templates from capability-writing skill
7. **Run validation checks** before showing preview:
#### Frontmatter Validation
| Check | Component | Rule |
|-------|-----------|------|
| Required fields | All | `name` for skills/agents, `description` for all |
| Model value | All | Must be `haiku`, `sonnet`, or `opus` (or absent) |
| Tools list | Agents | Only valid tool names: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Task`, `TodoWrite` |
| Skills reference | Agents | Each skill in list must exist in `skills/*/SKILL.md` |
#### Content Validation
| Check | Component | Rule |
|-------|-----------|------|
| Trigger conditions | Skills | Description must explain when to use (not just what) |
| Step instructions | Commands | Must have numbered steps with `**Step**:` format |
| Behavior sections | Agents | Must have "When Invoked" or process section |
| Skill references | Commands | `@~/.claude/skills/name/SKILL.md` paths must be valid |
#### Convention Checks
| Check | Rule |
|-------|------|
| Skill file name | Must be `SKILL.md` (uppercase) |
| Command file name | Must be lowercase kebab-case |
| Agent file name | Must be `AGENT.md` (uppercase) |
| Directory structure | `skills/<name>/`, `commands/`, `agents/<name>/` |
| No duplicates | Name must not match existing capability |
8. **Check for anti-patterns** and warn:
| Anti-pattern | Detection | Warning |
|--------------|-----------|---------|
| Trigger in body | Skill body contains "when to use" | "Move trigger conditions to description frontmatter" |
| No tool restrictions | Read-only agent without `disallowedTools` | "Consider adding `disallowedTools: [Edit, Write]` for read-only agents" |
| Missing skill refs | Command mentions domain without `@` reference | "Add explicit skill reference: `@~/.claude/skills/name/SKILL.md`" |
| Overly broad tools | Agent allows all tools but does specific task | "Consider restricting tools to what's actually needed" |
| Generic naming | Name like `utils`, `helper`, `misc` | "Use specific domain-focused naming" |
| God capability | Single component handling multiple unrelated concerns | "Consider splitting into focused components" |
### Phase 5: Present and Confirm
9. **Show validation results**:
```
## Validation Results
[PASS] Frontmatter: All required fields present
[PASS] Model: sonnet is valid
[WARN] Anti-pattern: Agent allows all tools but only reads files
Recommendation: Add disallowedTools: [Edit, Write]
[PASS] Conventions: File names follow patterns
[PASS] No duplicates: Name is unique
Proceed with warnings? (y/n)
```
10. **Show file preview** with full content:
```
## Files to Create
### skills/migration-review/SKILL.md
```yaml
---
name: migration-review
description: >
Knowledge for reviewing database migrations...
---
```
### commands/review-migration.md
```yaml
---
description: Review database migrations for safety and best practices
---
```
```
11. **Ask for approval** (gate before file creation):
- "Create these files? (y/n)"
- If warnings exist: "There are warnings. Proceed anyway? (y/n)"
- **If user declines**: Stop here. Offer to adjust the generated content or cancel.
- **If user approves**: Proceed to Phase 6.
### Phase 6: Create Files
**Only execute this phase after user approval in step 11.**
12. **Create directories** if needed:
```bash
mkdir -p skills/<name>
mkdir -p agents/<name>
```
If directory creation fails, report the error and stop.
13. **Write files** to correct locations:
- `skills/<name>/SKILL.md`
- `commands/<name>.md`
- `agents/<name>/AGENT.md`
If any file write fails, report which files were created and which failed.
14. **Report success**:
```
## Capability Created
Files created:
- skills/migration-review/SKILL.md
- commands/review-migration.md
Next steps:
1. Run `make install` to symlink to ~/.claude/
2. Test with: /review-migration
3. Refine based on usage
```
## Validation Error Messages
Provide clear, actionable error messages:
| Error | Message |
|-------|---------|
| Missing name | "Skill requires `name` field in frontmatter" |
| Invalid model | "Model must be `haiku`, `sonnet`, or `opus`. Got: `gpt-4`" |
| Unknown tool | "Unknown tool `Search` in disallowedTools. Valid tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite" |
| Missing skill | "Agent references skill `foo` but `skills/foo/SKILL.md` does not exist" |
| Invalid path | "Skill reference `@~/.claude/skills/bar/SKILL.md` invalid - directory `skills/bar/` not found" |
| Duplicate name | "Capability `gitea` already exists at `skills/gitea/SKILL.md`" |
| Wrong file name | "Skill file must be named `SKILL.md`, not `skill.md`" |
## Example Session
```
User: /create-capability I want to add support for reviewing database migrations
Claude: I'll help you create a migration review capability. Let me ask a few questions:
1. Will this knowledge apply automatically when Claude sees migrations,
or should users explicitly invoke it?
User: Users should invoke it explicitly
Claude: 2. Does this need isolated context for deep analysis, or can it work
in the main conversation?
User: Isolated would be good for complex migrations
Claude: 3. Is this read-only analysis, or will it modify migration files?
User: Just analysis, read-only
Claude: Based on your answers, I recommend:
- **Command**: `/review-migration` - Entry point for users
- **Skill**: `migration-review` - Knowledge about safe migrations
- **Agent**: `migration-reviewer` - Isolated analysis (read-only)
For model selection:
- Command: `sonnet` (standard workflow)
- Agent: `sonnet` with `opus` upgrade path for complex cases
Let me gather details for each component...
[Continues with file generation, validation, and creation]
```
## Guidelines
- Always run full validation before showing preview
- Show warnings but allow override with explicit confirmation
- Validate skill references exist before creating dependent components
- Suggest related existing skills that could be referenced
- Keep generated content minimal - users can expand after testing

7
old/skills/create-issue/SKILL.md → commands/create-issue.md
View File

@@ -1,11 +1,6 @@
---
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
description: Create a new Gitea issue. Can create single issues or batch create from a plan.
argument-hint: [title] or "batch"
user-invocable: true
---
# Create Issue(s)

10
old/skills/create-repo/SKILL.md → commands/create-repo.md
View File

@@ -1,13 +1,7 @@
---
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
description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
argument-hint: <repo-name>
context: fork
user-invocable: true
---
# Create Repository
@@ -160,7 +154,7 @@ Create a new repository with Flowmade's standard structure.
- CI workflow template
- 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>"

16
old/skills/dashboard/SKILL.md → commands/dashboard.md
View File

@@ -1,10 +1,8 @@
---
name: dashboard
description: >
Show dashboard of open issues, PRs awaiting review, and CI status. Use when
checking project status, viewing issues/PRs, or when user says /dashboard.
description: Show dashboard of open issues, PRs awaiting review, and CI status.
# Model: haiku is sufficient for fetching and displaying data.
# This command only reads from Gitea and formats output - no complex reasoning needed.
model: haiku
user-invocable: true
---
# Repository Dashboard
@@ -57,7 +55,7 @@ Run `tea actions runs` to list recent workflow runs.
Present each section with a clear header. Example:
```
\`\`\`
## Open Issues (3)
| # | Title | Author |
@@ -80,11 +78,11 @@ Present each section with a clear header. Example:
| **[FAILURE]** | build | PR #16 | abc1234 | 2h ago |
| [SUCCESS] | build | main | def5678 | 5h ago |
| [SUCCESS] | lint | main | def5678 | 5h ago |
```
\`\`\`
If no CI is configured:
```
\`\`\`
## CI Status
No CI workflows configured for this repository.
```
\`\`\`

8
old/skills/groom/SKILL.md → commands/groom.md
View File

@@ -1,12 +1,6 @@
---
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
description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
argument-hint: [issue-number]
user-invocable: true
---
# Groom Issues

9
old/skills/improve/SKILL.md → commands/improve.md
View File

@@ -1,12 +1,7 @@
---
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
description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
argument-hint:
context: fork
user-invocable: true
---
# Improvement Analysis

9
old/skills/manifesto/SKILL.md → commands/manifesto.md
View File

@@ -1,11 +1,6 @@
---
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
user-invocable: true
description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
argument-hint:
---
# Organization Manifesto

8
old/skills/plan-issues/SKILL.md → commands/plan-issues.md
View File

@@ -1,13 +1,7 @@
---
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
description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
argument-hint: <feature-description>
context: fork
user-invocable: true
---
# Plan Feature: $1

8
old/skills/pr/SKILL.md → commands/pr.md
View File

@@ -1,11 +1,5 @@
---
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
description: Create a PR from current branch. Auto-generates title and description from branch name and commits.
---
# Create Pull Request

24
old/skills/retro/SKILL.md → commands/retro.md
View File

@@ -1,17 +1,11 @@
---
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
description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
argument-hint: [task-description]
user-invocable: true
---
# Retrospective
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/agents.
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/commands/agents.
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md
@@ -19,7 +13,7 @@ Capture insights from completed work as issues on the architecture repo. Issues
## Flow
```
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/agent
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/command/agent
```
The retro creates the issue. Encoding happens when the issue is worked on.
@@ -35,7 +29,7 @@ The retro creates the issue. Encoding happens when the issue is worked on.
3. **Identify insights**: For each insight, determine:
- **What was learned**: The specific insight
- **Where to encode it**: Which skill or agent should change?
- **Where to encode it**: Which skill, command, or agent should change?
- **Governance impact**: What does this mean for how we work?
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
@@ -51,6 +45,7 @@ The retro creates the issue. Encoding happens when the issue is worked on.
## Suggested Encoding
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
- [ ] \`commands/xxx.md\` - [what to add/change]
- [ ] \`agents/xxx/agent.md\` - [what to add/change]
## Governance
@@ -83,13 +78,14 @@ When encoding a learning issue, the implementer should:
## Encoded In
- `skills/xxx/SKILL.md` - [what was added/changed]
- `commands/xxx.md` - [what was added/changed]
## Governance
[What this means for how we work]
```
2. **Update skill/agent** with the encoded knowledge
2. **Update skill/command/agent** with the encoded knowledge
3. **Close the issue** with reference to the learning file and changes made
@@ -98,7 +94,7 @@ When encoding a learning issue, the implementer should:
| Insight Type | Encode In |
|--------------|-----------|
| How to use a tool | `skills/[tool]/SKILL.md` |
| Workflow improvement | `skills/[skill]/SKILL.md` (user-invocable) |
| Workflow improvement | `commands/[command].md` |
| Subtask behavior | `agents/[agent]/agent.md` |
| Organization belief | `manifesto.md` |
| Product direction | `vision.md` (in product repo) |
@@ -107,8 +103,8 @@ When encoding a learning issue, the implementer should:
Add appropriate labels to issues:
- `learning` - Always add this
- `prompt-improvement` - For skill text changes
- `new-feature` - For new skills/agents
- `prompt-improvement` - For command/skill text changes
- `new-feature` - For new commands/skills/agents
- `bug` - For things that are broken
## Guidelines

8
old/skills/review-pr/SKILL.md → commands/review-pr.md
View File

@@ -1,12 +1,6 @@
---
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
description: Review a Gitea pull request. Fetches PR details, diff, and comments. Includes both code review and software architecture review.
argument-hint: <pr-number>
user-invocable: true
---
# Review PR #$1

11
old/skills/roadmap/SKILL.md → commands/roadmap.md
View File

@@ -1,11 +1,10 @@
---
name: roadmap
description: >
View current issues as a roadmap. Shows open issues organized by status and
dependencies. Use when viewing roadmap, checking issue status, or when user
says /roadmap.
description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
# Model: haiku is sufficient for fetching and organizing issue data.
# This command reads issues and dependencies, then displays them in categories.
# Basic categorization logic doesn't require advanced reasoning.
model: haiku
user-invocable: true
argument-hint:
---
# Roadmap View

94
old/skills/spawn-issues/SKILL.md → commands/spawn-issues.md
View File

@@ -1,10 +1,7 @@
---
name: spawn-issues
description: Orchestrate parallel issue implementation with review cycles
model: haiku
argument-hint: <issue-number> [<issue-number>...]
allowed-tools: Bash, Task, Read, TaskOutput
user-invocable: true
description: Orchestrate parallel issue implementation with review cycles
argument-hint: <issue-number> [<issue-number>...]
---
# Spawn Issues (Orchestrator)
@@ -65,34 +62,13 @@ Usage: /spawn-issues <issue-number> [<issue-number>...]
Example: /spawn-issues 42 43 44
```
### Step 2: Get Repository Info and Setup Worktrees
### Step 2: Get Repository Info
```bash
REPO_PATH=$(pwd)
REPO_NAME=$(basename $REPO_PATH)
# Create parent worktrees directory
mkdir -p "${REPO_PATH}/../worktrees"
WORKTREES_DIR="${REPO_PATH}/../worktrees"
```
For each issue, create the worktree upfront:
```bash
# Fetch latest from origin
cd "${REPO_PATH}"
git fetch origin
# Get issue details for branch naming
ISSUE_TITLE=$(tea issues <ISSUE_NUMBER> | grep "TITLE" | head -1)
BRANCH_NAME="issue-<ISSUE_NUMBER>-<kebab-title>"
# Create worktree for this issue
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-<ISSUE_NUMBER>" \
-b "${BRANCH_NAME}" origin/main
```
Track the worktree path for each issue.
### Step 3: Spawn All Issue Workers
For each issue number, spawn a background issue-worker agent and track its task_id:
@@ -129,11 +105,12 @@ Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- Issue number: <NUMBER>
- Worktree path: <WORKTREE_PATH>
Process:
1. Setup worktree:
cd <WORKTREE_PATH>
cd <REPO_PATH> && git fetch origin
git worktree add ../<REPO_NAME>-issue-<NUMBER> -b issue-<NUMBER>-<short-title> origin/main
cd ../<REPO_NAME>-issue-<NUMBER>
2. Get issue: tea issues <NUMBER> --comments
@@ -146,7 +123,7 @@ Process:
6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
Capture the PR number.
7. Cleanup: No cleanup needed - orchestrator handles worktree removal
7. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-issue-<NUMBER> --force
8. Output EXACTLY this format (orchestrator parses it):
ISSUE_WORKER_RESULT
@@ -204,17 +181,8 @@ implementing → (worker done) → reviewing → (approved) → DONE
### Step 5: Spawn Reviewers and Fixers
When spawning reviewers/fixers, create worktrees for them and pass the path.
For review, create a review worktree from the PR branch:
```bash
cd "${REPO_PATH}"
git fetch origin
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-<PR_NUMBER>" \
origin/<BRANCH_NAME>
```
Pass this worktree path to the reviewer/fixer agents.
When spawning reviewers, pass the PR number AND branch name from the issue worker result.
Each reviewer/fixer uses its own worktree for isolation - this prevents parallel agents from interfering with each other.
**Code Reviewer:**
```
@@ -230,12 +198,15 @@ You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.
Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- PR number: <PR_NUMBER>
- Worktree path: <WORKTREE_PATH>
- PR branch: <BRANCH_NAME>
Process:
1. Move to worktree:
cd <WORKTREE_PATH>
1. Setup worktree for isolated review:
cd <REPO_PATH> && git fetch origin
git worktree add ../<REPO_NAME>-review-<PR_NUMBER> origin/<BRANCH_NAME>
cd ../<REPO_NAME>-review-<PR_NUMBER>
2. Get PR details: tea pulls <PR_NUMBER> --comments
@@ -249,7 +220,7 @@ Process:
5. Post review comment: tea comment <PR_NUMBER> "<review summary>"
6. Cleanup: No cleanup needed - orchestrator handles worktree removal
6. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-review-<PR_NUMBER> --force
7. Output EXACTLY this format:
REVIEW_RESULT
@@ -295,14 +266,17 @@ You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.
Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- PR number: <NUMBER>
- Worktree path: <WORKTREE_PATH>
Process:
1. Move to worktree:
cd <WORKTREE_PATH>
1. Get feedback: tea pulls <NUMBER> --comments
2. Get feedback: tea pulls <NUMBER> --comments
2. Setup worktree from PR branch:
cd <REPO_PATH> && git fetch origin
git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
cd ../<REPO_NAME>-pr-<NUMBER>
git checkout <branch-name>
3. Address each piece of feedback
@@ -310,7 +284,7 @@ Process:
git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
git push
5. Cleanup: No cleanup needed - orchestrator handles worktree removal
5. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
6. Output EXACTLY:
PR_FIXER_RESULT
@@ -321,29 +295,9 @@ Process:
Work autonomously. If feedback is unclear, make reasonable judgment calls.
```
## Worktree Cleanup
After all issues reach terminal state, clean up all worktrees:
```bash
# Remove all worktrees created for this run
for worktree in "${WORKTREES_DIR}"/*; do
if [ -d "$worktree" ]; then
cd "${REPO_PATH}"
git worktree remove "$worktree" --force
fi
done
# Remove worktrees directory if empty
rmdir "${WORKTREES_DIR}" 2>/dev/null || true
```
**Important:** Always clean up worktrees, even if the orchestration failed partway through.
## Error Handling
- If an issue-worker fails, continue with others
- If a review fails, mark as "review-failed" and continue
- If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
- Always report final status even if some items failed
- Always clean up all worktrees before exiting

7
old/skills/spawn-pr-fixes/SKILL.md → commands/spawn-pr-fixes.md
View File

@@ -1,10 +1,7 @@
---
name: spawn-pr-fixes
description: Spawn parallel background agents to address PR review feedback
model: haiku
argument-hint: [pr-number...]
allowed-tools: Bash, Task, Read
user-invocable: true
description: Spawn parallel background agents to address PR review feedback
argument-hint: [pr-number...]
---
# Spawn PR Fixes

9
old/skills/update-claude-md/SKILL.md → commands/update-claude-md.md
View File

@@ -1,12 +1,7 @@
---
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
description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
argument-hint:
context: fork
user-invocable: true
---
# Update CLAUDE.md

13
old/skills/vision/SKILL.md → commands/vision.md
View File

@@ -1,11 +1,6 @@
---
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
description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
argument-hint: [goals]
user-invocable: true
---
# Product Vision
@@ -13,12 +8,12 @@ user-invocable: true
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md
This skill manages **product-level** vision. For organization-level vision, use `/manifesto`.
This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
## Architecture
| Level | Document | Purpose | Skill |
|-------|----------|---------|-------|
| Level | Document | Purpose | Command |
|-------|----------|---------|---------|
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |

7
old/skills/work-issue/SKILL.md → commands/work-issue.md
View File

@@ -1,11 +1,6 @@
---
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
description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
argument-hint: <issue-number>
user-invocable: true
---
# Work on Issue #$1

709
docs/writing-agents.md Normal file
View File

@@ -0,0 +1,709 @@
# 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
View File

@@ -1,508 +0,0 @@
# 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

731
docs/writing-commands.md Normal file
View File

@@ -0,0 +1,731 @@
# 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

578
docs/writing-skills.md Normal file
View File

@@ -0,0 +1,578 @@
# 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

13
learnings/README.md
View File

@@ -4,7 +4,7 @@ This folder captures learnings from retrospectives and day-to-day work. Learning
1. **Historical record**: What we learned and when
2. **Governance reference**: Why we work the way we do
3. **Encoding source**: Input that gets encoded into skills and agents
3. **Encoding source**: Input that gets encoded into skills, commands, and agents
## The Learning Flow
@@ -17,7 +17,7 @@ Experience → Learning captured → Encoded into system → Knowledge is action
- Periodic review
```
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.
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.
## Writing a Learning
@@ -40,7 +40,8 @@ The insight we gained. Be specific and actionable.
Where this learning has been (or will be) encoded:
- `skills/xxx/SKILL.md` - What was added/changed
- `agents/xxx/AGENT.md` - What was added/changed
- `commands/xxx.md` - What was added/changed
- `agents/xxx/agent.md` - What was added/changed
If not yet encoded, note: "Pending: Issue #XX"
@@ -53,7 +54,7 @@ What this learning means for how we work going forward. This is the "why" that j
1. **Capture the learning** in this folder
2. **Create an issue** to encode it into the appropriate location
3. **Update the skill/agent** with the encoded knowledge
3. **Update the skill/command/agent** with the encoded knowledge
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.
@@ -62,8 +63,8 @@ The goal: Claude should be able to *use* the learning, not just *read* about it.
| Learning Type | Encode In |
|---------------|-----------|
| How to use a tool | `skills/` (background skill) |
| Workflow improvement | `skills/` (user-invocable skill) |
| How to use a tool | `skills/` |
| Workflow improvement | `commands/` |
| Subtask behavior | `agents/` |
| Organization belief | `manifesto.md` |
| Product direction | `vision.md` (in product repo) |

157
old/skills/issue-writing/SKILL.md
View File

@@ -1,157 +0,0 @@
---
name: issue-writing
model: haiku
description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
user-invocable: false
---
# Issue Writing
How to write clear, actionable issues.
## Issue Structure
### Title
- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
- Be specific: "Add user authentication" not "Auth stuff"
- Keep under 60 characters when possible
### Description
```markdown
## Summary
One paragraph explaining what and why.
## Acceptance Criteria
- [ ] Specific, testable requirement
- [ ] Another requirement
- [ ] User can verify this works
## Context
Additional background, links, or references.
## Technical Notes (optional)
Implementation hints or constraints.
```
## Writing Acceptance Criteria
Good criteria are:
- **Specific**: "User sees error message" not "Handle errors"
- **Testable**: Can verify pass/fail
- **User-focused**: What the user experiences
- **Independent**: Each stands alone
Examples:
```markdown
- [ ] Login form validates email format before submission
- [ ] Invalid credentials show "Invalid email or password" message
- [ ] Successful login redirects to dashboard
- [ ] Session persists across browser refresh
```
## Vertical Slices
Issues should be **vertical slices** that deliver user-visible value.
### The Demo Test
Before writing an issue, ask: **Can a user demo or test this independently?**
- **Yes** → Good issue scope
- **No** → Rethink the breakdown
### Good vs Bad Issue Titles
| Good (Vertical) | Bad (Horizontal) |
|-----------------|------------------|
| "User can save and reload diagram" | "Add persistence layer" |
| "Show error when login fails" | "Add error handling" |
| "Domain expert can list orders" | "Add query syntax to ADL" |
### Writing User-Focused Issues
Frame issues around user capabilities:
```markdown
# Bad: Technical task
Title: Add email service integration
# Good: User capability
Title: User receives confirmation email after signup
```
The technical work is the same, but the good title makes success criteria clear.
## Issue Types
### Bug Report
```markdown
## Summary
Description of the bug.
## Steps to Reproduce
1. Go to...
2. Click...
3. Observe...
## Expected Behavior
What should happen.
## Actual Behavior
What happens instead.
## Environment
- Browser/OS/Version
```
### Feature Request
```markdown
## Summary
What feature and why it's valuable.
## Acceptance Criteria
- [ ] ...
## User Story (optional)
As a [role], I want [capability] so that [benefit].
```
### Technical Task
```markdown
## Summary
What technical work needs to be done.
## Scope
- Include: ...
- Exclude: ...
## Acceptance Criteria
- [ ] ...
```
## Labels
Use labels to categorize:
- `bug`, `feature`, `enhancement`, `refactor`
- `priority/high`, `priority/low`
- Component labels specific to project
## Dependencies
Identify and link dependencies when creating issues:
1. **In the description**, document dependencies:
```markdown
## Dependencies
- Depends on #12 (must complete first)
- Related to #15 (informational)
```
2. **After creating the issue**, formally link blockers using tea CLI:
```bash
tea issues deps add <this-issue> <blocker-issue>
tea issues deps add 5 3 # Issue #5 is blocked by #3
```
This creates a formal dependency graph that tools can query.

15
settings.json
View File

@@ -1,4 +1,5 @@
{
"model": "opus",
"permissions": {
"allow": [
"Bash(git:*)",
@@ -9,6 +10,13 @@
"WebSearch"
]
},
"statusLine": {
"type": "command",
"command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""
},
"enabledPlugins": {
"gopls-lsp@claude-plugins-official": true
},
"hooks": {
"PreToolUse": [
{
@@ -22,12 +30,5 @@
]
}
]
},
"statusLine": {
"type": "command",
"command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""
},
"enabledPlugins": {
"gopls-lsp@claude-plugins-official": true
}
}

1
old/skills/backlog-grooming/SKILL.md → skills/backlog-grooming/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: backlog-grooming
model: haiku
description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
user-invocable: false
---

482
skills/capability-writing/SKILL.md
View File

@@ -2,117 +2,23 @@
name: capability-writing
description: >
Guide for designing and creating capabilities for the architecture repository.
A capability is a cohesive set of components (skill + agent).
Use when creating new skills, agents, or extending the
A capability is a cohesive set of components (skill + command + agent).
Use when creating new skills, commands, or agents, or when extending the
AI workflow system. Includes templates, design guidance, and conventions.
user-invocable: false
---
# Capability Writing
How to design and create capabilities for the architecture repository using Anthropic's latest best practices (January 2025).
## Core Principles (NEW)
### 1. Conciseness is Critical
**Default assumption: Claude already knows.**
- Don't explain git, tea, standard CLI tools
- Don't explain concepts Claude understands
- Only add domain-specific context
- Keep main SKILL.md under 500 lines
**Bad:** "Git is a version control system. The commit command saves changes..."
**Good:** "`git commit -m 'feat: add feature'`"
### 2. Progressive Disclosure
Skills can bundle reference files and scripts that load/execute on-demand:
```
skill-name/
├── SKILL.md # Main workflow (200-500 lines)
├── best-practices.md # Detailed guidance (loaded when referenced)
├── examples/
│ ├── example1.md
│ └── example2.md
├── reference/
│ ├── api-docs.md
│ └── checklists.md
└── scripts/ # Bundled with this skill
├── validate.sh # Executed, not loaded into context
└── process.sh
```
**Benefits:**
- Main SKILL.md stays concise
- Reference files load only when Claude references them
- Scripts execute without consuming context tokens
- Each skill is self-contained
### 3. Script Bundling
Bundle error-prone bash operations as scripts within the skill:
**Instead of inline bash:**
```markdown
5. Create PR: `tea pulls create --title "..." --description "..."`
```
**Bundle a script:**
```markdown
5. **Create PR**: `./scripts/create-pr.sh $issue "$title"`
```
```bash
# In skill-name/scripts/create-pr.sh
#!/bin/bash
set -e
# Script handles errors, retries, validation
```
**When to bundle scripts:**
- Operations with complex error handling
- Operations that need retries
- Operations with multiple validation steps
- Fragile bash operations
### 4. Degrees of Freedom
Match instruction style to task fragility:
| Degree | When | Example |
|--------|------|---------|
| **High** (text) | Multiple valid approaches | "Review code quality and suggest improvements" |
| **Medium** (template) | Preferred pattern with variation | "Use this template, customize as needed" |
| **Low** (script) | Fragile operation, exact sequence | "Run: `./scripts/validate.sh`" |
### 5. Model Selection (UPDATED)
**New guidance:** Default to Haiku, justify if not.
| Model | Use When | Cost vs Haiku |
|-------|----------|---------------|
| **Haiku** | Simple workflows, validated steps, with scripts | Baseline |
| **Sonnet** | When Haiku testing shows <80% success rate | 12x more expensive |
| **Opus** | Deep reasoning, architectural judgment | 60x more expensive |
**Haiku works well when:**
- Steps are simple and validated
- Instructions are concise
- Error-prone operations use scripts
- Outputs have structured templates
**Test with Haiku first.** Only upgrade if needed.
How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together.
## Component Overview
| Component | Location | Purpose | Example |
|-----------|----------|---------|---------|
| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard |
| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing |
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer |
| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |
## When to Use Each Component
@@ -122,58 +28,60 @@ Match instruction style to task fragility:
Start here: What do you need?
|
+--> Just knowledge to apply automatically?
| --> Background skill (user-invocable: false)
| --> Skill only
|
+--> User-initiated workflow?
| --> User-invocable skill (user-invocable: true)
+--> User-initiated workflow using existing knowledge?
| --> Command (reference skills via @)
|
+--> Complex isolated work needing focused context?
| --> User-invocable skill + Agent
| --> Command + Agent (agent uses skills)
|
+--> New domain expertise + workflow + isolated work?
--> Full capability (background skill + user-invocable skill + agent)
--> Full capability (all three)
```
**Detailed decision criteria:** See [best-practices.md](best-practices.md)
### Decision Matrix
| Need | Component | Example |
|------|-----------|---------|
| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
| User-invoked workflow | Command | /work-issue, /dashboard |
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
| All three working together | Full capability | arch-review (skill + command + agent) |
### Signs You Need Each Component
**Create a Skill when:**
- You explain the same concepts repeatedly
- Quality is inconsistent without explicit guidance
- Multiple commands need the same knowledge
- There is a clear domain that does not fit existing skills
**Create a Command when:**
- Same workflow is used multiple times
- User explicitly triggers the action
- Approval checkpoints are needed
- Multiple tools need orchestration
**Create an Agent when:**
- Task requires deep exploration that would pollute main context
- Multiple skills work better together
- Batch processing or parallel execution is needed
- Specialist persona improves outputs
## Component Templates
### User-Invocable Skill Template
### 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
```
**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)
### Background Skill Template
Location: `skills/<name>/SKILL.md`
```yaml
---
name: skill-name
description: >
What this skill teaches and when to use it.
Include trigger conditions in description.
Include trigger conditions in description (not body).
List specific capabilities users would mention.
user-invocable: false
---
@@ -182,87 +90,178 @@ user-invocable: false
Brief description of what this skill covers.
## Core Concepts
Explain fundamental ideas Claude needs to understand.
## Patterns and Templates
Provide reusable structures and formats.
## Guidelines
List rules, best practices, and quality standards.
## Examples
Show concrete illustrations of the skill in action.
## Common Mistakes
Document pitfalls to avoid.
## Reference
Quick-reference tables, checklists, or commands.
```
**Complete template:** See [templates/background-skill.md](templates/background-skill.md)
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to use (max 1024 chars) |
| `user-invocable` | No | Set `false` for reference-only skills |
| `model` | No | Specific model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
### Command Template
Location: `commands/<name>.md`
```yaml
---
description: What this command does (one-line summary)
argument-hint: <required> [optional]
model: sonnet
---
# Command Title
@~/.claude/skills/relevant-skill/SKILL.md
1. **First step**: What to do
2. **Second step**: What to do next
3. **Ask for approval** before significant actions
4. **Execute** the approved actions
5. **Present results** with links and summary
```
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | One-line summary for help/listings |
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
| `model` | No | Override model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
### Agent Template
Location: `agents/<name>/AGENT.md`
```yaml
---
name: agent-name
description: What this agent does and when to spawn it
model: haiku
model: sonnet
skills: skill1, skill2
disallowedTools:
- Edit # For read-only agents
- Edit
- Write
---
You are a [role] specialist that [primary function].
## When Invoked
1. **Gather context**
2. **Analyze**
3. **Act**
4. **Report**
Describe the process the agent follows:
1. **Gather context**: What information to collect
2. **Analyze**: What to evaluate
3. **Act**: What actions to take
4. **Report**: How to communicate results
## Output Format
Describe expected output structure.
## Guidelines
- Behavioral rules
- Constraints
- Quality standards
```
**Complete template:** See [templates/agent.md](templates/agent.md)
**Frontmatter fields:**
**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to spawn |
| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` |
| `skills` | No | Comma-separated skill names (not paths) |
| `disallowedTools` | No | Tools to block (e.g., Edit, Write for read-only) |
| `permissionMode` | No | `default` or `bypassPermissions` |
## Structure Examples
## Model Selection Guidance
### Simple Skill (< 300 lines, no scripts)
```
skills/simple-skill/
└── SKILL.md
```
| Model | Use When | Examples |
|-------|----------|----------|
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer |
| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor |
### Progressive Disclosure (with reference files)
```
skills/complex-skill/
├── SKILL.md (~200 lines)
├── reference/
│ ├── detailed-guide.md
│ └── api-reference.md
└── examples/
└── usage-examples.md
```
### Decision Criteria
### With Bundled Scripts
```
skills/skill-with-scripts/
├── SKILL.md
├── reference/
│ └── error-handling.md
└── scripts/
├── validate.sh
└── process.sh
```
- **Start with `sonnet`** - handles most tasks well
- **Use `haiku` for volume** - speed and cost matter at scale
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
- **Consider the stakes** - higher consequence tasks warrant more capable models
**Detailed examples:** See [examples/](examples/) folder
## Naming Conventions
### File and Folder Names
| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
| Skill file | UPPERCASE | `SKILL.md` |
| Command file | kebab-case | `work-issue.md`, `review-pr.md` |
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
| Agent file | UPPERCASE | `AGENT.md` |
### Naming Patterns
**Skills:** Name after the domain or knowledge area
- Good: `gitea`, `issue-writing`, `software-architecture`
- Bad: `utils`, `helpers`, `misc`
**Commands:** Use verb or verb-phrase (actions)
- Good: `work-issue`, `review-pr`, `create-issue`
- Bad: `issue-work`, `pr-review`, `issue`
**Agents:** Name by role or persona (recognizable specialist)
- Good: `code-reviewer`, `issue-worker`, `software-architect`
- Bad: `helper`, `do-stuff`, `agent1`
## Referencing Skills
### In User-Invocable Skills
### In Commands
Use `@` file reference syntax to guarantee background skill content is loaded:
Use the `@` file reference syntax to guarantee skill content is loaded:
```markdown
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
```
**Important:** Do NOT use phrases like "Use the gitea skill" - file references guarantee the content is available.
**Important:** Do NOT use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the content is available.
### In Agents
List skill names in frontmatter (not paths):
List skill names in the frontmatter (not paths):
```yaml
---
@@ -271,16 +270,24 @@ skills: gitea, issue-writing, backlog-grooming
---
```
The agent runtime loads these skills automatically.
## Common Patterns
### Approval Workflow
### Approval Workflow (Commands)
Always ask before significant actions:
```markdown
4. **Present plan** for approval
5. **If approved**, create the issues
6. **Present summary** with links
```
### Conditional Behavior
### Conditional Behavior (Commands)
Handle optional arguments with mode switching:
```markdown
## If issue number provided ($1):
1. Fetch specific issue
@@ -291,12 +298,18 @@ skills: gitea, issue-writing, backlog-grooming
2. Process each
```
### Spawning Agents
### Spawning Agents from Commands
Delegate complex subtasks:
```markdown
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
```
### Read-Only Agents
For analysis without modification:
```yaml
---
name: code-reviewer
@@ -306,53 +319,106 @@ disallowedTools:
---
```
## Quick Reference
## Anti-Patterns to Avoid
**Frontmatter fields:** See [reference/frontmatter-fields.md](reference/frontmatter-fields.md)
**Model selection:** See [reference/model-selection.md](reference/model-selection.md)
**Anti-patterns:** See [reference/anti-patterns.md](reference/anti-patterns.md)
**Best practices:** See [best-practices.md](best-practices.md)
### Overly Broad Components
## Naming Conventions
**Bad:** One skill/command/agent that does everything
```markdown
# Project Management
Handles issues, PRs, releases, documentation, deployment...
```
| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
| Skill file | UPPERCASE | `SKILL.md` |
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
| Agent file | UPPERCASE | `AGENT.md` |
**Good:** Focused components with clear responsibility
```markdown
# Issue Writing
How to write clear, actionable issues.
```
**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)
### Vague Instructions
**Bad:**
```markdown
1. Handle the issue
2. Do the work
3. Finish up
```
**Good:**
```markdown
1. **View the issue** with `--comments` flag
2. **Create branch**: `git checkout -b issue-$1-<title>`
3. **Commit** with message referencing the issue
```
### Missing Skill References
**Bad:**
```markdown
Use the gitea skill to create an issue.
```
**Good:**
```markdown
@~/.claude/skills/gitea/SKILL.md
Use `tea issues create --title "..." --description "..."`
```
### God Skills
**Bad:** Single skill with 1000+ lines covering unrelated topics
**Good:** Multiple focused skills that reference each other
### Premature Agent Creation
**Bad:** Creating an agent for every task
**Good:** Use agents only when you need:
- Context isolation
- Skill composition
- Parallel execution
- Specialist persona
## Detailed Documentation
For comprehensive guides, see the `docs/` directory:
- `docs/writing-skills.md` - Complete skill writing guide
- `docs/writing-commands.md` - Complete command writing guide
- `docs/writing-agents.md` - Complete agent writing guide
These documents include:
- Full frontmatter reference
- Annotated examples from the codebase
- Lifecycle management
- Integration checklists
## Checklists
### Before Creating a 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`
- [ ] **Model defaults to `haiku`** unless justified
### Before Creating a Background Skill
### Before Creating a Skill
- [ ] Knowledge is used in multiple places (not just once)
- [ ] Existing skills do not already cover this domain
- [ ] Content is specific and actionable (not generic)
- [ ] Frontmatter has `user-invocable: false`
- [ ] Description includes trigger terms
- [ ] Frontmatter has descriptive `description` with trigger terms
- [ ] File at `skills/<name>/SKILL.md`
### Before Creating a Command
- [ ] Workflow is repeatable (used multiple times)
- [ ] User explicitly triggers it (not automatic)
- [ ] Clear start and end points
- [ ] Skills referenced via `@~/.claude/skills/<name>/SKILL.md`
- [ ] Approval checkpoints before significant actions
- [ ] File at `commands/<name>.md`
### Before Creating an Agent
- [ ] Built-in agents (Explore, Plan) are not sufficient
- [ ] Context isolation or skill composition is needed
- [ ] Clear role/persona emerges
- [ ] `model` selection is deliberate (default to `haiku`)
- [ ] `model` selection is deliberate (not just `inherit`)
- [ ] `skills` list is right-sized (not too many)
- [ ] File at `agents/<name>/AGENT.md`

500
skills/capability-writing/best-practices.md
View File

@@ -1,500 +0,0 @@
# Skill Authoring Best Practices
Based on Anthropic's latest agent skills documentation (January 2025).
## Core Principles
### Concise is Key
> "The context window is a public good. Default assumption: Claude is already very smart."
**Only add context Claude doesn't already have.**
**Challenge each piece of information:**
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
**Good example (concise):**
```markdown
## Extract PDF text
Use pdfplumber:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
```
**Bad example (verbose):**
```markdown
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains text,
images, and other content. To extract text from a PDF, you'll need to use a library.
There are many libraries available for PDF processing, but we recommend pdfplumber
because it's easy to use and handles most cases well. First, you'll need to install
it using pip. Then you can use the code below...
```
The concise version assumes Claude knows what PDFs are and how libraries work.
### Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability.
#### High Freedom (Text-Based Instructions)
Use when multiple approaches are valid:
```markdown
## Code Review Process
1. Analyze code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability
4. Verify adherence to project conventions
```
#### Medium Freedom (Templates/Pseudocode)
Use when there's a preferred pattern but variation is acceptable:
```markdown
## Generate Report
Use this template and customize as needed:
\`\`\`python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
\`\`\`
```
#### Low Freedom (Exact Scripts)
Use when operations are fragile and error-prone:
```markdown
## Database Migration
Run exactly this script:
\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`
Do not modify the command or add additional flags.
```
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs**: One safe way forward. Provide specific guardrails (low freedom)
- **Open field**: Many paths lead to success. Give general direction (high freedom)
### Progressive Disclosure
Split large skills into layers that load on-demand.
#### Three Levels of Loading
| Level | When Loaded | Token Cost | Content |
|-------|------------|------------|---------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens | `name` and `description` from frontmatter |
| **Level 2: Instructions** | When skill is triggered | Under 5k tokens | SKILL.md body with instructions |
| **Level 3: Resources** | As needed | Unlimited | Referenced files, scripts |
#### Organizing Large Skills
**Pattern 1: High-level guide with references**
```markdown
# PDF Processing
## Quick Start
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
## Advanced Features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)
**Examples**: See [EXAMPLES.md](EXAMPLES.md)
```
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
**Pattern 2: Domain-specific organization**
For skills with multiple domains:
```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
```
When user asks about revenue, Claude reads only `reference/finance.md`.
**Pattern 3: Conditional details**
```markdown
# DOCX Processing
## Creating Documents
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).
## Editing Documents
For simple edits, modify XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
#### Avoid Deeply Nested References
**Keep references one level deep from SKILL.md.**
**Bad (too deep):**
```
SKILL.md → advanced.md → details.md → actual info
```
**Good (one level):**
```
SKILL.md → {advanced.md, reference.md, examples.md}
```
#### Structure Longer Files with TOC
For reference files >100 lines, include a table of contents:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and Setup
...
```
This ensures Claude can see the full scope even with partial reads.
## Script Bundling
### When to Bundle Scripts
Bundle scripts for:
- **Error-prone operations**: Complex bash with retry logic
- **Fragile sequences**: Operations requiring exact order
- **Validation steps**: Checking conditions before proceeding
- **Reusable utilities**: Operations used in multiple steps
**Benefits of bundled scripts:**
- More reliable than generated code
- Save tokens (no code in context)
- Save time (no code generation)
- Ensure consistency
### Script Structure
```bash
#!/bin/bash
# script-name.sh - Brief description
#
# Usage: script-name.sh <param1> <param2>
#
# Example: script-name.sh issue-42 "Fix bug"
set -e # Exit on error
# Input validation
if [ $# -lt 2 ]; then
echo "Usage: $0 <param1> <param2>"
exit 1
fi
param1=$1
param2=$2
# Main logic with error handling
if ! some_command; then
echo "ERROR: Command failed"
exit 1
fi
# Success output
echo "SUCCESS: Operation completed"
```
### Referencing Scripts in Skills
**Make clear whether to execute or read:**
**Execute (most common):**
```markdown
7. **Create PR**: `./scripts/create-pr.sh $1 "$title"`
```
**Read as reference (for understanding complex logic):**
```markdown
See `./scripts/analyze-form.py` for the field extraction algorithm
```
### Solving, Not Punting
Scripts should handle error conditions, not punt to Claude.
**Good (handles errors):**
```python
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"File {path} not found, creating default")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
print(f"Cannot access {path}, using default")
return ''
```
**Bad (punts to Claude):**
```python
def process_file(path):
return open(path).read() # Fails, Claude has to figure it out
```
## Workflow Patterns
### Plan-Validate-Execute
Add verification checkpoints to catch errors early.
**Example: Workflow with validation**
```markdown
## PDF Form Filling
Copy this checklist:
\`\`\`
Progress:
- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
\`\`\`
**Step 1: Analyze**
Run: `python scripts/analyze_form.py input.pdf`
**Step 2: Create Mapping**
Edit `fields.json`
**Step 3: Validate**
Run: `python scripts/validate_fields.py fields.json`
Fix any errors before continuing.
**Step 4: Fill**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
```
### Feedback Loops
**Pattern:** Run validator → fix errors → repeat
**Example: Document editing**
```markdown
1. Make edits to `word/document.xml`
2. **Validate**: `python scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review error message
- Fix issues
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
6. Test output document
```
## Model Selection
### Decision Framework
```
Start with Haiku
|
v
Test on 3-5 representative tasks
|
+-- Success rate ≥80%? ---------> Use Haiku ✓
|
+-- Success rate <80%? --------> Try Sonnet
|
v
Test on same tasks
|
+-- Success ≥80%? --> Use Sonnet
|
+-- Still failing? --> Opus or redesign task
```
### Haiku Works Well When
- **Steps are simple and validated**
- **Instructions are concise** (no verbose explanations)
- **Error-prone operations use scripts** (deterministic)
- **Outputs have structured templates**
- **Checklists replace open-ended judgment**
### Testing with Multiple Models
Test skills with all models you plan to use:
1. **Create test cases:** 3-5 representative scenarios
2. **Run with Haiku:** Measure success rate, response quality
3. **Run with Sonnet:** Compare results
4. **Adjust instructions:** If Haiku struggles, add clarity or scripts
What works for Opus might need more detail for Haiku.
## Common Anti-Patterns
### Offering Too Many Options
**Bad (confusing):**
```markdown
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...
```
**Good (provide default):**
```markdown
Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
\`\`\`
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
```
### Time-Sensitive Information
**Bad (will become wrong):**
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good (use "old patterns" section):**
```markdown
## Current Method
Use the v2 API: `api.example.com/v2/messages`
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
### Inconsistent Terminology
**Good (consistent):**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad (inconsistent):**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
### Windows-Style Paths
Always use forward slashes:
- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
- ✗ **Bad**: `scripts\helper.py`, `reference\guide.md`
Unix-style paths work cross-platform.
## Iterative Development
### Build Evaluations First
Create test cases BEFORE extensive documentation:
1. **Identify gaps**: Run Claude on tasks without skill, document failures
2. **Create evaluations**: Build 3-5 test scenarios
3. **Establish baseline**: Measure Claude's performance without skill
4. **Write minimal instructions**: Just enough to pass evaluations
5. **Iterate**: Execute evaluations, refine
### Develop Iteratively with Claude
**Use Claude to help write skills:**
1. **Complete a task without skill**: Work through problem, note what context you provide
2. **Identify reusable pattern**: What context is useful for similar tasks?
3. **Ask Claude to create skill**: "Create a skill that captures this pattern"
4. **Review for conciseness**: Remove unnecessary explanations
5. **Test on similar tasks**: Use skill with fresh Claude instance
6. **Iterate based on observation**: Where does Claude struggle?
Claude understands skill format natively - no special prompts needed.
## Checklist for Effective Skills
**Before publishing:**
### Core Quality
- [ ] Description is specific and includes key terms
- [ ] Description includes what skill does AND when to use it
- [ ] SKILL.md body under 500 lines
- [ ] Additional details in separate files (if needed)
- [ ] No time-sensitive information
- [ ] Consistent terminology throughout
- [ ] Examples are concrete, not abstract
- [ ] File references are one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
### Code and Scripts
- [ ] Scripts solve problems, don't punt to Claude
- [ ] Error handling is explicit and helpful
- [ ] No "magic numbers" (all values justified)
- [ ] Required packages listed and verified
- [ ] Scripts have clear documentation
- [ ] No Windows-style paths (all forward slashes)
- [ ] Validation steps for critical operations
- [ ] Feedback loops for quality-critical tasks
### Testing
- [ ] At least 3 test cases created
- [ ] Tested with Haiku (if that's the target)
- [ ] Tested with real usage scenarios
- [ ] Team feedback incorporated (if applicable)

129
skills/capability-writing/examples/progressive-disclosure.md
View File

@@ -1,129 +0,0 @@
# Example: Progressive Disclosure Skill
A skill that uses reference files to keep the main SKILL.md concise.
## Structure
```
skills/database-query/
├── SKILL.md (~200 lines)
├── reference/
│ ├── schemas.md (table schemas)
│ ├── common-queries.md (frequently used queries)
│ └── optimization-tips.md (performance guidance)
└── examples/
├── simple-select.md
└── complex-join.md
```
## When to Use
- Skill content would be >500 lines
- Multiple domains or topics
- Reference documentation is large
- Want to keep main workflow concise
## Example: database-query (main SKILL.md)
```markdown
---
name: database-query
description: >
Help users query the PostgreSQL database with proper schemas and optimization.
Use when user needs to write SQL queries or mentions database/tables.
user-invocable: false
---
# Database Query Helper
Help write efficient, correct SQL queries for our PostgreSQL database.
## Quick Start
\`\`\`sql
SELECT id, name, created_at
FROM users
WHERE status = 'active'
LIMIT 10;
\`\`\`
## Table Schemas
We have 3 main schemas:
- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
## Common Queries
For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
- User activity reports
- Sales summaries
- Inventory status
## Writing Queries
1. **Identify tables**: Which schemas does this query need?
2. **Check schema**: Load relevant schema from reference
3. **Write query**: Use proper column names and types
4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
## Examples
- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
```
## Example: reference/schemas.md
```markdown
# Database Schemas
## Users
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| email | VARCHAR(255) | Unique email |
| name | VARCHAR(100) | Display name |
| status | ENUM('active','inactive','banned') | Account status |
| created_at | TIMESTAMP | Account creation |
| updated_at | TIMESTAMP | Last update |
## Products
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| name | VARCHAR(200) | Product name |
| price | DECIMAL(10,2) | Price in USD |
| inventory | INTEGER | Stock count |
| category_id | UUID | FK to categories |
## Orders
[...more tables...]
```
## Why This Works
- **Main file stays concise** (~200 lines)
- **Details load on-demand**: schemas.md loads when user asks about specific table
- **Fast for common cases**: Simple queries don't need reference files
- **Scalable**: Can add more schemas without bloating main file
## Loading Pattern
1. User: "Show me all active users"
2. Claude reads SKILL.md (sees Users schema reference)
3. Claude: "I'll load the users schema to get column names"
4. Claude reads reference/schemas.md#users
5. Claude writes correct query
## What Makes It Haiku-Friendly
- ✓ Main workflow is simple ("identify → check schema → write query")
- ✓ Reference files provide facts, not reasoning
- ✓ Clear pointers to where details are
- ✓ Examples show patterns

71
skills/capability-writing/examples/simple-workflow.md
View File

@@ -1,71 +0,0 @@
# Example: Simple Workflow Skill
A basic skill with just a SKILL.md file - no scripts or reference files needed.
## Structure
```
skills/list-open-prs/
└── SKILL.md
```
## When to Use
- Skill is simple (<300 lines)
- No error-prone bash operations
- No need for reference documentation
- Straightforward workflow
## Example: list-open-prs
```markdown
---
name: list-open-prs
description: >
List all open pull requests for the current repository.
Use when user wants to see PRs or says /list-open-prs.
model: haiku
user-invocable: true
---
# List Open PRs
@~/.claude/skills/gitea/SKILL.md
Show all open pull requests in the current repository.
## Process
1. **Get repository info**
- `git remote get-url origin`
- Parse owner/repo from URL
2. **Fetch open PRs**
- `tea pulls list --state open --output simple`
3. **Format results** as table
| PR # | Title | Author | Created |
|------|-------|--------|---------|
| ... | ... | ... | ... |
## Guidelines
- Show most recent PRs first
- Include link to each PR
- If no open PRs, say "No open pull requests"
```
## Why This Works
- **Concise**: Entire skill fits in ~30 lines
- **Simple commands**: Just git and tea CLI
- **No error handling needed**: tea handles errors gracefully
- **Structured output**: Table format is clear
## What Makes It Haiku-Friendly
- ✓ Simple sequential steps
- ✓ Clear commands with no ambiguity
- ✓ Structured output format
- ✓ No complex decision-making

210
skills/capability-writing/examples/with-scripts.md
View File

@@ -1,210 +0,0 @@
# Example: Skill with Bundled Scripts
A skill that bundles helper scripts for error-prone operations.
## Structure
```
skills/deploy-to-staging/
├── SKILL.md
├── reference/
│ └── rollback-procedure.md
└── scripts/
├── validate-build.sh
├── deploy.sh
└── health-check.sh
```
## When to Use
- Operations have complex error handling
- Need retry logic
- Multiple validation steps
- Fragile bash commands
## Example: deploy-to-staging (main SKILL.md)
```markdown
---
name: deploy-to-staging
description: >
Deploy current branch to staging environment with validation and health checks.
Use when deploying to staging or when user says /deploy-to-staging.
model: haiku
user-invocable: true
---
# Deploy to Staging
Deploy current branch to staging with automated validation and rollback capability.
## Process
1. **Validate build**
- `./scripts/validate-build.sh`
- Checks tests pass, linter clean, no uncommitted changes
2. **Show deployment plan** for approval
- Branch name
- Latest commit
- Services that will be updated
3. **If approved, deploy**
- `./scripts/deploy.sh staging $branch`
- Script handles Docker build, push, k8s apply
4. **Health check**
- `./scripts/health-check.sh staging`
- Verifies all services are healthy
5. **Report results**
- Deployment URL
- Status of each service
- Rollback command if needed
## Rollback
If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)
```
## Example: scripts/validate-build.sh
```bash
#!/bin/bash
# validate-build.sh - Pre-deployment validation
#
# Checks:
# - Tests pass
# - Linter clean
# - No uncommitted changes
# - Docker builds successfully
set -e
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'
error() {
echo -e "${RED}ERROR: $1${NC}" >&2
exit 1
}
success() {
echo -e "${GREEN}✓ $1${NC}"
}
# Check 1: No uncommitted changes
if ! git diff-index --quiet HEAD --; then
error "Uncommitted changes detected. Commit or stash first."
fi
success "No uncommitted changes"
# Check 2: Tests pass
if ! npm test > /dev/null 2>&1; then
error "Tests failing. Fix tests before deploying."
fi
success "Tests pass"
# Check 3: Linter clean
if ! npm run lint > /dev/null 2>&1; then
error "Linter errors. Run 'npm run lint' to see details."
fi
success "Linter clean"
# Check 4: Docker builds
if ! docker build -t test-build . > /dev/null 2>&1; then
error "Docker build failed"
fi
success "Docker build successful"
echo ""
echo -e "${GREEN}✓ All validations passed${NC}"
```
## Example: scripts/deploy.sh
```bash
#!/bin/bash
# deploy.sh - Deploy to environment
#
# Usage: deploy.sh <environment> <branch>
# Example: deploy.sh staging feature-new-ui
set -e
ENVIRONMENT=$1
BRANCH=$2
if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
echo "Usage: $0 <environment> <branch>"
exit 1
fi
echo "Deploying $BRANCH to $ENVIRONMENT..."
# Build Docker image
docker build -t myapp:$BRANCH .
# Tag for registry
docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH
# Push to registry with retry
for i in {1..3}; do
if docker push registry.example.com/myapp:$BRANCH; then
break
fi
echo "Push failed, retrying ($i/3)..."
sleep 5
done
# Update Kubernetes deployment
kubectl set image deployment/myapp \
myapp=registry.example.com/myapp:$BRANCH \
-n $ENVIRONMENT
# Wait for rollout
kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m
echo "Deployment complete!"
echo "URL: https://$ENVIRONMENT.example.com"
```
## Why This Works
**Script benefits:**
- **Deterministic**: Same behavior every time
- **Error handling**: Retries, clear messages
- **Validation**: Pre-flight checks prevent bad deployments
- **No token cost**: Scripts execute without loading code into context
**Skill stays simple:**
- Main SKILL.md is ~30 lines
- Just calls scripts in order
- No complex bash logic inline
- Easy to test scripts independently
## What Makes It Haiku-Friendly
- ✓ Skill has simple instructions ("run script X, then Y")
- ✓ Scripts handle all complexity
- ✓ Clear success/failure from script exit codes
- ✓ Validation prevents ambiguous states
- ✓ Structured output from scripts is easy to parse
## Testing Scripts
Scripts can be tested independently:
```bash
# Test validation
./scripts/validate-build.sh
# Test deployment (dry-run)
./scripts/deploy.sh staging test-branch --dry-run
# Test health check
./scripts/health-check.sh staging
```
This makes the skill more reliable than inline bash.

536
skills/capability-writing/reference/anti-patterns.md
View File

@@ -1,536 +0,0 @@
# Anti-Patterns to Avoid
Common mistakes when creating skills and agents.
## Skill Design Anti-Patterns
### 1. Overly Broad Components
**Bad:** One skill that does everything
```yaml
---
name: project-management
description: Handles issues, PRs, releases, documentation, deployment, testing, CI/CD...
---
# Project Management
This skill does:
- Issue management
- Pull request reviews
- Release planning
- Documentation
- Deployment
- Testing
- CI/CD configuration
...
```
**Why it's bad:**
- Huge context window usage
- Hard to maintain
- Unclear when to trigger
- Tries to do too much
**Good:** Focused components
```yaml
---
name: issue-writing
description: How to write clear, actionable issues with acceptance criteria.
---
```
**Separate skills for:**
- `issue-writing` - Issue quality
- `review-pr` - PR reviews
- `gitea` - CLI reference
- Each does one thing well
---
### 2. Vague Instructions
**Bad:**
```markdown
1. Handle the issue
2. Do the work
3. Finish up
4. Let me know when done
```
**Why it's bad:**
- No clear actions
- Claude has to guess
- Inconsistent results
- Hard to validate
**Good:**
```markdown
1. **View issue**: `tea issues $1 --comments`
2. **Create branch**: `git checkout -b issue-$1-<title>`
3. **Plan work**: Use TodoWrite to break down steps
4. **Implement**: Make necessary changes
5. **Commit**: `git commit -m "feat: ..."`
6. **Create PR**: `tea pulls create --title "..." --description "..."`
```
---
### 3. Missing Skill References
**Bad:**
```markdown
Use the gitea skill to create an issue.
```
**Why it's bad:**
- Skills have ~20% auto-activation rate
- Claude might not load the skill
- Inconsistent results
**Good:**
```markdown
@~/.claude/skills/gitea/SKILL.md
Use `tea issues create --title "..." --description "..."`
```
**The `@` reference guarantees the skill content is loaded.**
---
### 4. God Skills
**Bad:** Single 1500-line skill covering everything
```
skills/database/SKILL.md (1500 lines)
- PostgreSQL
- MySQL
- MongoDB
- Redis
- All queries
- All optimization tips
- All schemas
```
**Why it's bad:**
- Exceeds recommended 500 lines
- Loads everything even if you need one thing
- Hard to maintain
- Wastes tokens
**Good:** Progressive disclosure
```
skills/database/
├── SKILL.md (200 lines - overview)
├── reference/
│ ├── postgres.md
│ ├── mysql.md
│ ├── mongodb.md
│ └── redis.md
└── schemas/
├── users.md
├── products.md
└── orders.md
```
Claude loads only what's needed.
---
### 5. Premature Agent Creation
**Bad:** Creating an agent for every task
```
agents/
├── issue-viewer/
├── branch-creator/
├── commit-maker/
├── pr-creator/
└── readme-updater/
```
**Why it's bad:**
- Overhead of spawning agents
- Most tasks don't need isolation
- Harder to follow workflow
- Slower execution
**Good:** Use agents only when needed:
- Context isolation (parallel work)
- Skill composition (multiple skills together)
- Specialist persona (architecture review)
**Simple tasks → Skills**
**Complex isolated work → Agents**
---
### 6. Verbose Explanations
**Bad:**
```markdown
Git is a distributed version control system that was created by Linus Torvalds in 2005. It allows multiple developers to work on the same codebase simultaneously while maintaining a complete history of all changes. When you want to save your changes, you use the git commit command, which creates a snapshot of your current working directory...
```
**Why it's bad:**
- Wastes tokens
- Claude already knows git
- Slows down loading
- Adds no value
**Good:**
```markdown
`git commit -m 'feat: add feature'`
```
**Assume Claude is smart. Only add domain-specific context.**
---
## Instruction Anti-Patterns
### 7. Offering Too Many Options
**Bad:**
```markdown
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula, or...
```
**Why it's bad:**
- Decision paralysis
- Inconsistent choices
- No clear default
**Good:**
```markdown
Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
For scanned PDFs requiring OCR, use pdf2image + pytesseract instead.
```
**Provide default, mention alternative only when needed.**
---
### 8. Time-Sensitive Information
**Bad:**
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Why it's bad:**
- Will become wrong
- Requires maintenance
- Confusing after the date
**Good:**
```markdown
## Current Method
Use v2 API: `api.example.com/v2/messages`
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API: `api.example.com/v1/messages`
No longer supported.
</details>
```
---
### 9. Inconsistent Terminology
**Bad:** Mixing terms for the same thing
```markdown
1. Get the API endpoint
2. Call the URL
3. Hit the API route
4. Query the path
```
**Why it's bad:**
- Confusing
- Looks like different things
- Harder to search
**Good:** Pick one term and stick with it
```markdown
1. Get the API endpoint
2. Call the API endpoint
3. Check the API endpoint response
4. Retry the API endpoint if needed
```
---
### 10. Windows-Style Paths
**Bad:**
```markdown
Run: `scripts\helper.py`
See: `reference\guide.md`
```
**Why it's bad:**
- Fails on Unix systems
- Causes errors on Mac/Linux
**Good:**
```markdown
Run: `scripts/helper.py`
See: `reference/guide.md`
```
**Always use forward slashes. They work everywhere.**
---
## Script Anti-Patterns
### 11. Punting to Claude
**Bad script:**
```python
def process_file(path):
return open(path).read() # Let Claude handle errors
```
**Why it's bad:**
- Script fails with no helpful message
- Claude has to guess what happened
- Inconsistent error handling
**Good script:**
```python
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"ERROR: File {path} not found")
print("Creating default file...")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
print(f"ERROR: Cannot access {path}")
print("Using default value")
return ''
```
**Scripts should solve problems, not punt to Claude.**
---
### 12. Magic Numbers
**Bad:**
```bash
TIMEOUT=47 # Why 47?
RETRIES=5 # Why 5?
DELAY=3.7 # Why 3.7?
```
**Why it's bad:**
- No one knows why these values
- Hard to adjust
- "Voodoo constants"
**Good:**
```bash
# HTTP requests typically complete in <30s
# Extra buffer for slow connections
TIMEOUT=30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by retry 2
RETRIES=3
# Exponential backoff: 1s, 2s, 4s
INITIAL_DELAY=1
```
**Document why each value is what it is.**
---
## Model Selection Anti-Patterns
### 13. Always Using Sonnet/Opus
**Bad:**
```yaml
---
name: dashboard
model: opus # "Just to be safe"
---
```
**Why it's bad:**
- 60x more expensive than Haiku
- 5x slower
- Wasted cost for simple task
**Good:**
```yaml
---
name: dashboard
model: haiku # Tested: 5/5 tests passed
---
```
**Test with Haiku first. Only upgrade if needed.**
---
### 14. Never Testing Haiku
**Bad:**
```yaml
---
name: review-pr
model: sonnet # Assumed it needs Sonnet, never tested Haiku
---
```
**Why it's bad:**
- Might work fine with Haiku
- Missing 12x cost savings
- Missing 2.5x speed improvement
**Good:**
```yaml
---
name: review-pr
model: haiku # Tested: Haiku 4/5 (80%), good enough!
---
```
Or:
```yaml
---
name: review-pr
model: sonnet # Tested: Haiku 2/5 (40%), Sonnet 4/5 (80%)
---
```
**Always test Haiku first, document results.**
---
## Progressive Disclosure Anti-Patterns
### 15. Deeply Nested References
**Bad:**
```
SKILL.md → advanced.md → details.md → actual-info.md
```
**Why it's bad:**
- Claude may partially read nested files
- Information might be incomplete
- Hard to navigate
**Good:**
```
SKILL.md → {advanced.md, reference.md, examples.md}
```
**Keep references one level deep from SKILL.md.**
---
### 16. No Table of Contents for Long Files
**Bad:** 500-line reference file with no structure
```markdown
# Reference
(500 lines of content with no navigation)
```
**Why it's bad:**
- Hard to preview
- Claude might miss sections
- User can't navigate
**Good:**
```markdown
# Reference
## Contents
- Authentication and setup
- Core methods
- Advanced features
- Error handling
- Examples
## Authentication and Setup
...
```
**Files >100 lines should have TOC.**
---
## Checklist to Avoid Anti-Patterns
Before publishing a skill:
- [ ] Not overly broad (does one thing well)
- [ ] Instructions are specific (not vague)
- [ ] Skill references use `@` syntax
- [ ] Under 500 lines (or uses progressive disclosure)
- [ ] Only creates agents when needed
- [ ] Concise (assumes Claude knows basics)
- [ ] Provides default, not 10 options
- [ ] No time-sensitive information
- [ ] Consistent terminology
- [ ] Forward slashes for paths
- [ ] Scripts handle errors, don't punt
- [ ] No magic numbers in scripts
- [ ] Tested with Haiku first
- [ ] References are one level deep
- [ ] Long files have table of contents

278
skills/capability-writing/reference/frontmatter-fields.md
View File

@@ -1,278 +0,0 @@
# Frontmatter Fields Reference
Complete documentation of all available frontmatter fields for skills and agents.
## Skill Frontmatter
### Required Fields
#### `name`
- **Type:** string
- **Required:** Yes
- **Format:** Lowercase, hyphens only, no spaces
- **Max length:** 64 characters
- **Must match:** Directory name
- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
- **Example:** `work-issue`, `code-review`, `gitea`
#### `description`
- **Type:** string (multiline supported with `>`)
- **Required:** Yes
- **Max length:** 1024 characters
- **Cannot contain:** XML tags
- **Should include:**
- What the skill does
- When to use it
- Trigger conditions
- **Example:**
```yaml
description: >
View, create, and manage Gitea issues and pull requests.
Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
```
#### `user-invocable`
- **Type:** boolean
- **Required:** Yes
- **Values:** `true` or `false`
- **Usage:**
- `true`: User can trigger with `/skill-name`
- `false`: Background skill, auto-loaded when needed
### Optional Fields
#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`
- **Default:** Inherits from parent (usually haiku)
- **Guidance:** Default to `haiku`, only upgrade if needed
- **Example:**
```yaml
model: haiku # 12x cheaper than sonnet
```
#### `argument-hint`
- **Type:** string
- **Required:** No (only for user-invocable skills)
- **Format:** `<required>` for required params, `[optional]` for optional
- **Shows in UI:** Helps users know what arguments to provide
- **Example:**
```yaml
argument-hint: <issue-number>
argument-hint: <issue-number> [optional-title]
```
#### `context`
- **Type:** string
- **Required:** No
- **Values:** `fork`
- **Usage:** Set to `fork` for skills needing isolated context
- **When to use:** Heavy exploration tasks that would pollute main context
- **Example:**
```yaml
context: fork # For arch-review-repo, deep exploration
```
#### `allowed-tools`
- **Type:** list of strings
- **Required:** No
- **Usage:** Restrict which tools the skill can use
- **Example:**
```yaml
allowed-tools:
- Read
- Bash
- Grep
```
- **Note:** Rarely used, most skills have all tools
## Agent Frontmatter
### Required Fields
#### `name`
- **Type:** string
- **Required:** Yes
- **Same rules as skill name**
#### `description`
- **Type:** string
- **Required:** Yes
- **Should include:**
- What the agent does
- When to spawn it
- **Example:**
```yaml
description: >
Automated code review of pull requests for quality, bugs, security, and style.
Spawn when reviewing PRs or checking code quality.
```
### Optional Fields
#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
- **Default:** `inherit` (uses parent's model)
- **Guidance:**
- Default to `haiku` for simple agents
- Use `sonnet` for balanced performance
- Reserve `opus` for deep reasoning
- **Example:**
```yaml
model: haiku # Fast and cheap for code review checklist
```
#### `skills`
- **Type:** comma-separated list of skill names (not paths)
- **Required:** No
- **Usage:** Auto-load these skills when agent spawns
- **Format:** Just skill names, not paths
- **Example:**
```yaml
skills: gitea, issue-writing, code-review
```
- **Note:** Agent runtime loads skills automatically
#### `disallowedTools`
- **Type:** list of tool names
- **Required:** No
- **Common use:** Make agents read-only
- **Example:**
```yaml
disallowedTools:
- Edit
- Write
```
- **When to use:** Analysis agents that shouldn't modify code
#### `permissionMode`
- **Type:** string
- **Required:** No
- **Values:** `default`, `bypassPermissions`
- **Usage:** Rarely used, for agents that need to bypass permission prompts
- **Example:**
```yaml
permissionMode: bypassPermissions
```
## Examples
### Minimal User-Invocable Skill
```yaml
---
name: dashboard
description: Show open issues, PRs, and CI status.
user-invocable: true
---
```
### Full-Featured Skill
```yaml
---
name: work-issue
description: >
Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
Use when implementing issues or when user says /work-issue.
model: haiku
argument-hint: <issue-number>
user-invocable: true
---
```
### Background Skill
```yaml
---
name: gitea
description: >
View, create, and manage Gitea issues and PRs using tea CLI.
Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
user-invocable: false
---
```
### Read-Only Agent
```yaml
---
name: code-reviewer
description: >
Automated code review of pull requests for quality, bugs, security, style, and test coverage.
model: sonnet
skills: gitea, code-review
disallowedTools:
- Edit
- Write
---
```
### Implementation Agent
```yaml
---
name: issue-worker
description: >
Autonomously implements a single issue in an isolated git worktree.
model: haiku
skills: gitea, issue-writing, software-architecture
---
```
## Validation Rules
### Name Validation
- Must be lowercase
- Must use hyphens (not underscores or spaces)
- Cannot contain: `anthropic`, `claude`
- Cannot contain XML tags `<`, `>`
- Max 64 characters
- Must match directory name exactly
### Description Validation
- Cannot be empty
- Max 1024 characters
- Cannot contain XML tags
- Should end with period
### Model Validation
- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
- Case-sensitive (must be lowercase)
## Common Mistakes
**Bad: Using paths in skills field**
```yaml
skills: ~/.claude/skills/gitea/SKILL.md # Wrong!
```
**Good: Just skill names**
```yaml
skills: gitea, issue-writing
```
**Bad: Reserved word in name**
```yaml
name: claude-helper # Contains "claude"
```
**Good: Descriptive name**
```yaml
name: code-helper
```
**Bad: Vague description**
```yaml
description: Helps with stuff
```
**Good: Specific description**
```yaml
description: >
Analyze Excel spreadsheets, create pivot tables, generate charts.
Use when analyzing Excel files, spreadsheets, or .xlsx files.
```

336
skills/capability-writing/reference/model-selection.md
View File

@@ -1,336 +0,0 @@
# Model Selection Guide
Detailed guidance on choosing the right model for skills and agents.
## Cost Comparison
| Model | Input (per MTok) | Output (per MTok) | vs Haiku |
|-------|------------------|-------------------|----------|
| **Haiku** | $0.25 | $1.25 | Baseline |
| **Sonnet** | $3.00 | $15.00 | 12x more expensive |
| **Opus** | $15.00 | $75.00 | 60x more expensive |
**Example cost for typical skill call (2K input, 1K output):**
- Haiku: $0.00175
- Sonnet: $0.021 (12x more)
- Opus: $0.105 (60x more)
## Speed Comparison
| Model | Tokens/Second | vs Haiku |
|-------|---------------|----------|
| **Haiku** | ~100 | Baseline |
| **Sonnet** | ~40 | 2.5x slower |
| **Opus** | ~20 | 5x slower |
## Decision Framework
```
Start with Haiku by default
|
v
Test on 3-5 representative tasks
|
+-- Success rate ≥80%? ---------> ✓ Use Haiku
| (12x cheaper, 2-5x faster)
|
+-- Success rate <80%? --------> Try Sonnet
| |
| v
| Test on same tasks
| |
| +-- Success ≥80%? --> Use Sonnet
| |
| +-- Still failing? --> Opus or redesign
|
v
Document why you chose the model
```
## When Haiku Works Well
### ✓ Ideal for Haiku
**Simple sequential workflows:**
- `/dashboard` - Fetch and display
- `/roadmap` - List and format
- `/commit` - Generate message from diff
**Workflows with scripts:**
- Error-prone operations in scripts
- Skills just orchestrate script calls
- Validation is deterministic
**Structured outputs:**
- Tasks with clear templates
- Format is defined upfront
- No ambiguous formatting
**Reference/knowledge skills:**
- `gitea` - CLI reference
- `issue-writing` - Patterns and templates
- `software-architecture` - Best practices
### Examples of Haiku Success
**work-issue skill:**
- Sequential steps (view → branch → plan → implement → PR)
- Each step has clear validation
- Scripts handle error-prone operations
- Success rate: ~90%
**dashboard skill:**
- Fetch data (tea commands)
- Format as table
- Clear, structured output
- Success rate: ~95%
## When to Use Sonnet
### Use Sonnet When
**Haiku fails 20%+ of the time**
- Test with Haiku first
- If success rate <80%, upgrade to Sonnet
**Complex judgment required:**
- Code review (quality assessment)
- Issue grooming (clarity evaluation)
- Architecture decisions
**Nuanced reasoning:**
- Understanding implicit requirements
- Making trade-off decisions
- Applying context-dependent rules
### Examples of Sonnet Success
**review-pr skill:**
- Requires code understanding
- Judgment about quality/bugs
- Context-dependent feedback
- Originally tried Haiku: 65% success → Sonnet: 85%
**issue-worker agent:**
- Autonomous implementation
- Pattern matching
- Architectural decisions
- Originally tried Haiku: 70% success → Sonnet: 82%
## When to Use Opus
### Reserve Opus For
**Deep architectural reasoning:**
- `software-architect` agent
- Pattern recognition across large codebases
- Identifying subtle anti-patterns
- Trade-off analysis
**High-stakes decisions:**
- Breaking changes analysis
- System-wide refactoring plans
- Security architecture review
**Complex pattern recognition:**
- Requires sophisticated understanding
- Multiple layers of abstraction
- Long-term implications
### Examples of Opus Success
**software-architect agent:**
- Analyzes entire codebase
- Identifies 8 different anti-patterns
- Provides prioritized recommendations
- Sonnet: 68% success → Opus: 88%
**arch-review-repo skill:**
- Comprehensive architecture audit
- Cross-cutting concerns
- System-wide patterns
- Opus justified for depth
## Making Haiku More Effective
If Haiku is struggling, try these improvements **before** upgrading to Sonnet:
### 1. Add Validation Steps
**Instead of:**
```markdown
3. Implement changes and create PR
```
**Try:**
```markdown
3. Implement changes
4. Validate: Run `./scripts/validate.sh` (tests pass, linter clean)
5. Create PR: `./scripts/create-pr.sh`
```
### 2. Bundle Error-Prone Operations in Scripts
**Instead of:**
```markdown
5. Create PR: `tea pulls create --title "..." --description "..."`
```
**Try:**
```markdown
5. Create PR: `./scripts/create-pr.sh $issue "$title"`
```
### 3. Add Structured Output Templates
**Instead of:**
```markdown
Show the results
```
**Try:**
```markdown
Format results as:
| Issue | Status | Link |
|-------|--------|------|
| ... | ... | ... |
```
### 4. Add Explicit Checklists
**Instead of:**
```markdown
Review the code for quality
```
**Try:**
```markdown
Check:
- [ ] Code quality (readability, naming)
- [ ] Bugs (edge cases, null checks)
- [ ] Tests (coverage, assertions)
```
### 5. Make Instructions More Concise
**Instead of:**
```markdown
Git is a version control system. When you want to commit changes, you use the git commit command which saves your changes to the repository...
```
**Try:**
```markdown
`git commit -m 'feat: add feature'`
```
## Testing Methodology
### Create Test Suite
For each skill, create 3-5 test cases:
**Example: work-issue skill tests**
1. Simple bug fix issue
2. New feature with acceptance criteria
3. Issue missing acceptance criteria
4. Issue with tests that fail
5. Complex refactoring task
### Test with Haiku
```bash
# Set skill to Haiku
model: haiku
# Run all 5 tests
# Document success/failure for each
```
### Measure Success Rate
```
Success rate = (Successful tests / Total tests) × 100
```
**Decision:**
- ≥80% → Keep Haiku
- <80% → Try Sonnet
- <50% → Likely need Opus or redesign
### Test with Sonnet (if needed)
```bash
# Upgrade to Sonnet
model: sonnet
# Run same 5 tests
# Compare results
```
### Document Decision
```yaml
---
name: work-issue
model: haiku # Tested: 4/5 tests passed with Haiku (80%)
---
```
Or:
```yaml
---
name: review-pr
model: sonnet # Tested: Haiku 3/5 (60%), Sonnet 4/5 (80%)
---
```
## Common Patterns
### Pattern: Start Haiku, Upgrade if Needed
**Issue-worker agent evolution:**
1. **V1 (Haiku):** 70% success - struggled with pattern matching
2. **Analysis:** Added more examples, still 72%
3. **V2 (Sonnet):** 82% success - better code understanding
4. **Decision:** Keep Sonnet, document why
### Pattern: Haiku for Most, Sonnet for Complex
**Review-pr skill:**
- Static analysis steps: Haiku could handle
- Manual code review: Needs Sonnet judgment
- **Decision:** Use Sonnet for whole skill (simplicity)
### Pattern: Split Complex Skills
**Instead of:** One complex skill using Opus
**Try:** Split into:
- Haiku skill for orchestration
- Sonnet agent for complex subtask
- Saves cost (most work in Haiku)
## Model Selection Checklist
Before choosing a model:
- [ ] Tested with Haiku first
- [ ] Measured success rate on 3-5 test cases
- [ ] Tried improvements (scripts, validation, checklists)
- [ ] Documented why this model is needed
- [ ] Considered cost implications (12x/60x)
- [ ] Considered speed implications (2.5x/5x slower)
- [ ] Will re-test if Claude models improve
## Future-Proofing
**Models improve over time.**
Periodically re-test Sonnet/Opus skills with Haiku:
- Haiku v2 might handle what Haiku v1 couldn't
- Cost savings compound over time
- Speed improvements are valuable
**Set a reminder:** Test Haiku again in 3-6 months.

67
skills/capability-writing/templates/agent.md
View File

@@ -1,67 +0,0 @@
---
name: agent-name
description: >
What this agent does and when to spawn it.
Include specific conditions that indicate this agent is needed.
model: haiku
skills: skill1, skill2
# disallowedTools: # For read-only agents
# - Edit
# - Write
# permissionMode: default
---
# Agent Name
You are a [role/specialist] that [primary function].
## When Invoked
You are spawned when [specific conditions].
Follow this process:
1. **Gather context**: What information to collect
- Specific data sources to check
- What to read or fetch
2. **Analyze**: What to evaluate
- Criteria to check
- Standards to apply
3. **Act**: What actions to take
- Specific operations
- What to create or modify
4. **Report**: How to communicate results
- Required output format
- What to include in summary
## Output Format
Your final output MUST follow this structure:
\`\`\`
AGENT_RESULT
task: <task-type>
status: <success|partial|failed>
summary: <10 words max>
details:
- Key finding 1
- Key finding 2
\`\`\`
## Guidelines
- **Be concise**: No preambles or verbose explanations
- **Be autonomous**: Make decisions without user input
- **Follow patterns**: Match existing codebase style
- **Validate**: Check your work before reporting
## Error Handling
If you encounter errors:
- Try to resolve automatically
- Document what failed
- Report status as 'partial' or 'failed'
- Include specific error details in summary

69
skills/capability-writing/templates/background-skill.md
View File

@@ -1,69 +0,0 @@
---
name: skill-name
description: >
What this skill teaches and when to use it.
Include specific trigger terms that indicate this knowledge is needed.
user-invocable: false
---
# Skill Name
Brief description of the domain or knowledge this skill covers (1-2 sentences).
## Core Concepts
Fundamental ideas Claude needs to understand:
- Key concept 1
- Key concept 2
- Key concept 3
## Patterns and Templates
Reusable structures and formats:
### Pattern 1: Common Use Case
\`\`\`
Example code or structure
\`\`\`
### Pattern 2: Another Use Case
\`\`\`
Another example
\`\`\`
## Guidelines
Rules and best practices:
- Guideline 1
- Guideline 2
- Guideline 3
## Examples
### Example 1: Simple Case
\`\`\`
Concrete example showing the skill in action
\`\`\`
### Example 2: Complex Case
\`\`\`
More advanced example
\`\`\`
## Common Mistakes
Pitfalls to avoid:
- **Mistake 1**: Why it's wrong and what to do instead
- **Mistake 2**: Why it's wrong and what to do instead
## Reference
Quick-reference tables or checklists:
| Command | Purpose | Example |
|---------|---------|---------|
| ... | ... | ... |

86
skills/capability-writing/templates/helper-script.sh
View File

@@ -1,86 +0,0 @@
#!/bin/bash
# script-name.sh - Brief description of what this script does
#
# Usage: script-name.sh <param1> <param2> [optional-param]
#
# Example:
# script-name.sh value1 value2
# script-name.sh value1 value2 optional-value
#
# Exit codes:
# 0 - Success
# 1 - Invalid arguments or general error
# 2 - Specific error condition (document what)
set -e # Exit immediately on error
# set -x # Uncomment for debugging
# Color output for better visibility
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Helper functions
error() {
echo -e "${RED}ERROR: $1${NC}" >&2
exit 1
}
success() {
echo -e "${GREEN}SUCCESS: $1${NC}"
}
warn() {
echo -e "${YELLOW}WARNING: $1${NC}"
}
# Input validation
if [ $# -lt 2 ]; then
echo "Usage: $0 <param1> <param2> [optional-param]"
echo ""
echo "Description: Brief description of what this does"
echo ""
echo "Arguments:"
echo " param1 Description of param1"
echo " param2 Description of param2"
echo " optional-param Description of optional param (default: value)"
exit 1
fi
# Parse arguments
PARAM1=$1
PARAM2=$2
OPTIONAL_PARAM=${3:-"default-value"}
# Validate inputs
if [ -z "$PARAM1" ]; then
error "param1 cannot be empty"
fi
# Main logic
main() {
echo "Processing with param1=$PARAM1, param2=$PARAM2..."
# Step 1: Describe what this step does
if ! some_command "$PARAM1"; then
error "Failed to process param1"
fi
# Step 2: Another operation with error handling
result=$(another_command "$PARAM2" 2>&1)
if [ $? -ne 0 ]; then
error "Failed to process param2: $result"
fi
# Step 3: Validation
if [ ! -f "$result" ]; then
error "Expected file not found: $result"
fi
success "Operation completed successfully"
echo "$result" # Output for caller to parse
}
# Execute main function
main

65
skills/capability-writing/templates/user-invocable-skill.md
View File

@@ -1,65 +0,0 @@
---
name: skill-name
description: >
Clear description of what this skill does and when to use it.
Use when [specific trigger conditions] or when user says /skill-name.
model: haiku
argument-hint: <required-param> [optional-param]
user-invocable: true
# context: fork # Use for skills needing isolated context
# allowed-tools: # Restrict tools if needed
# - Read
# - Bash
---
# Skill Title
@~/.claude/skills/relevant-background-skill/SKILL.md
Brief intro explaining the skill's purpose (1-2 sentences max).
## Process
1. **First step**: Clear action with specific command or instruction
- `command or tool to use`
- What to look for or validate
2. **Second step**: Next action
- Specific details
- Expected output
3. **Ask for approval** before significant actions
- Show what will be created/modified
- Wait for user confirmation
4. **Execute** the approved actions
- Run commands/create files
- Handle errors gracefully
5. **Present results** with links and summary
- Structured output (table or list)
- Links to created resources
## Guidelines
- Keep responses concise
- Use structured output (tables, lists)
- No preambles or sign-offs
- Validate inputs before acting
## Output Format
Use this structure for responses:
\`\`\`
## Summary
[1-2 sentences]
## Results
| Item | Status | Link |
|------|--------|------|
| ... | ... | ... |
## Next Steps
- ...
\`\`\`

1
old/skills/claude-md-writing/SKILL.md → skills/claude-md-writing/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: claude-md-writing
model: haiku
description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
user-invocable: false
---

1
old/skills/code-review/SKILL.md → skills/code-review/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: code-review
model: haiku
description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
user-invocable: false
---

197
skills/create-capability/SKILL.md
View File

@@ -1,197 +0,0 @@
---
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: claude-haiku-4-5
argument-hint: <description>
user-invocable: true
---
# Create Capability
@~/.claude/skills/capability-writing/SKILL.md
Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).
## Process
1. **Understand the capability**: Analyze "$1" to understand what the user wants to build
- What domain or workflow does this cover?
- What user need does it address?
- What existing capabilities might overlap?
2. **Determine components needed**: Based on the description, recommend which components:
| Pattern | When to Use |
|---------|-------------|
| Skill only (background) | Knowledge to apply automatically (reused across other skills) |
| Skill only (user-invocable) | User-invoked workflow |
| Skill + Agent | Workflow with isolated worker for complex subtasks |
| Full set | New domain expertise + workflow + isolated work |
Present recommendation with reasoning:
```
## Recommended Components for: $1
Based on your description, I recommend:
- **Skill**: `name` - [why this knowledge is needed]
- **Agent**: `name` - [why isolation/specialization is needed] (optional)
Reasoning: [explain why this combination fits the need]
```
3. **Analyze complexity** (NEW): For each skill, determine structure needed:
**Ask these questions:**
a) **Expected size**: Will this skill be >300 lines?
- If NO → Simple structure (just SKILL.md)
- If YES → Suggest progressive disclosure
b) **Error-prone operations**: Are there complex bash operations?
- Check for: PR creation, worktree management, complex git operations
- If YES → Suggest bundling scripts
c) **Degree of freedom**: What instruction style is appropriate?
- Multiple valid approaches → Text instructions (high freedom)
- Preferred pattern with variation → Templates (medium freedom)
- Fragile operations, exact sequence → Scripts (low freedom)
**Present structure recommendation:**
```
## Recommended Structure
Based on complexity analysis:
- **Size**: [Simple | Progressive disclosure]
- **Scripts**: [None | Bundle error-prone operations]
- **Degrees of freedom**: [High | Medium | Low]
Structure:
[Show folder structure diagram]
```
4. **Gather information**: For each recommended component, ask:
**For all components:**
- Name (kebab-case, descriptive)
- Description (one-line summary including trigger conditions)
**For Skills:**
- What domain/knowledge does this cover?
- What are the key concepts to teach?
- What patterns or templates should it include?
- Is it user-invocable (workflow) or background (reference)?
**For Agents:**
- What specialized role does this fill?
- What skills does it need?
- Should it be read-only (no Edit/Write)?
5. **Select appropriate models** (UPDATED):
**Default to Haiku, upgrade only if needed:**
| Model | Use For | Cost vs Haiku |
|-------|---------|---------------|
| `haiku` | Most skills and agents (DEFAULT) | Baseline |
| `sonnet` | When Haiku would struggle (<80% success rate) | 12x more expensive |
| `opus` | Deep reasoning, architectural analysis | 60x more expensive |
**Ask for justification if not Haiku:**
- "This looks like a simple workflow. Should we try Haiku first?"
- "Does this require complex reasoning that Haiku can't handle?"
For each component, recommend Haiku unless there's clear reasoning for Sonnet/Opus.
6. **Generate files**: Create content using templates from capability-writing skill
**Structure options:**
a) **Simple skill** (most common):
```
skills/skill-name/
└── SKILL.md
```
b) **Progressive disclosure** (for large skills):
```
skills/skill-name/
├── SKILL.md (~200-300 lines)
├── reference/
│ ├── detailed-guide.md
│ └── api-reference.md
└── examples/
└── usage-examples.md
```
c) **With bundled scripts** (for error-prone operations):
```
skills/skill-name/
├── SKILL.md
├── reference/
│ └── error-handling.md
└── scripts/
├── validate.sh
└── process.sh
```
**Ensure proper inter-references:**
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
- Agent lists skills in `skills:` frontmatter (names only, not paths)
- User-invocable skill spawns agent via Task tool if agent is part of the set
- Scripts are called with `./scripts/script-name.sh` in SKILL.md
7. **Present for approval**: Show all generated files with their full content:
```
## Generated Files
### skills/name/SKILL.md
[full content]
### skills/name/scripts/helper.sh (if applicable)
[full content]
### agents/name/AGENT.md (if applicable)
[full content]
Ready to create these files?
```
8. **Create files** in correct locations after approval:
- Create directories if needed
- `skills/<name>/SKILL.md`
- `skills/<name>/scripts/` (if scripts recommended)
- `skills/<name>/reference/` (if progressive disclosure)
- `agents/<name>/AGENT.md` (if agent recommended)
9. **Report success**:
```
## Capability Created: name
Files created:
- skills/name/SKILL.md
- skills/name/scripts/helper.sh (if applicable)
- agents/name/AGENT.md (if applicable)
## Guidelines (UPDATED)
- Follow all conventions from capability-writing skill
- **Default to Haiku** for all new skills/agents (12x cheaper, 2-5x faster)
- **Bundle scripts** for error-prone bash operations
- **Use progressive disclosure** for skills >500 lines
- Reference existing skills rather than duplicating knowledge
- Keep components focused - split if scope is too broad
- User-invocable skills should have approval checkpoints
- Skills should have descriptive `description` fields with trigger conditions
- **Be concise** - assume Claude knows basics
## Output Style
Be concise and direct:
- No preambles ("I'll help you...")
- No sign-offs ("Let me know...")
- Show structure diagrams clearly
- Use tables for comparisons
- One decision per section

136
skills/ddd-breakdown/SKILL.md
View File

@@ -1,136 +0,0 @@
---
name: ddd-breakdown
description: >
Analyze product vision using DDD to identify bounded contexts and generate
implementation issues. Use when breaking down features into DDD-based vertical
slices, or when user says /ddd-breakdown.
model: haiku
argument-hint: [vision-file]
user-invocable: true
---
# DDD Breakdown
@~/.claude/skills/ddd/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Analyze product vision through a DDD lens to generate implementation issues.
## Process
1. **Locate manifesto and vision**:
**Manifesto** (organization-level):
```bash
# Always in architecture repo
cat ~/.claude/manifesto.md
# Or if in architecture repo:
cat ./manifesto.md
```
**Vision** (product-level):
```bash
# If argument provided: use that file
# Otherwise: look for vision.md in current repo
cat ./vision.md
```
Verify both files exist before proceeding.
2. **Spawn DDD analyst agent**:
Use Task tool to spawn `ddd-analyst` agent:
```
Analyze this product using DDD principles.
Manifesto: [path to manifesto.md]
Vision: [path to vision.md]
Codebase: [current working directory]
Identify bounded contexts, map features to DDD patterns, and generate
user stories with DDD implementation guidance.
```
The agent will:
- Analyze manifesto (personas, beliefs, domain language)
- Analyze vision (goals, features, milestones)
- Explore codebase (existing structure, boundaries, misalignments)
- Identify bounded contexts (intended vs actual)
- Map features to DDD patterns (aggregates, commands, events)
- Generate user stories with acceptance criteria and DDD guidance
3. **Review agent output**:
The agent returns structured analysis:
- Bounded contexts identified
- User stories per context
- Refactoring needs
- Suggested implementation order
Present this to the user for review.
4. **Confirm issue creation**:
Ask user:
- Create all issues?
- Select specific issues to create?
- Modify any stories before creating?
5. **Create issues in Gitea**:
For each approved user story:
```bash
tea issues create \
--title "[story title]" \
--description "[full story with DDD guidance]"
```
Apply labels:
- `feature` (or `refactor` for refactoring issues)
- `bounded-context/[context-name]`
- Any other relevant labels from the story
6. **Link dependencies**:
For stories with dependencies:
```bash
tea issues deps add <dependent-issue> <blocker-issue>
```
7. **Report results**:
Show created issues with links:
```
## Issues Created
### Context: [Context Name]
- #123: [Issue title]
- #124: [Issue title]
### Context: [Another Context]
- #125: [Issue title]
### Refactoring
- #126: [Issue title]
View all: [link to issues page]
```
## Guidelines
- **Manifesto is organization-wide**: Always read from architecture repo
- **Vision is product-specific**: Read from current repo or provided path
- **Let agent do the analysis**: Don't try to identify contexts yourself, spawn the agent
- **Review before creating**: Always show user the analysis before creating issues
- **Label by context**: Use `bounded-context/[name]` labels for filtering
- **Link dependencies**: Use `tea issues deps add` for blockers
- **Implementation order matters**: Create foundational issues (refactoring, core aggregates) first
## Tips
- Run this when starting a new product or major feature area
- Re-run periodically to identify drift between vision and code
- Use with `/vision` skill to manage product vision
- Combine with `/plan-issues` for additional breakdown
- Review with team before creating all issues

272
skills/ddd/SKILL.md
View File

@@ -1,272 +0,0 @@
---
name: ddd
description: >
Domain-Driven Design concepts: bounded contexts, aggregates, commands, events,
and tactical patterns. Use when analyzing domain models, identifying bounded
contexts, or mapping features to DDD patterns.
user-invocable: false
---
# Domain-Driven Design (DDD)
Strategic and tactical patterns for modeling complex domains.
## Strategic DDD: Bounded Contexts
### What is a Bounded Context?
A **bounded context** is a boundary within which a domain model is consistent. Same terms can mean different things in different contexts.
**Example:** "Order" means different things in different contexts:
- **Sales Context**: Order = customer purchase with payment and shipping
- **Fulfillment Context**: Order = pick list for warehouse
- **Accounting Context**: Order = revenue transaction
### Identifying Bounded Contexts
Look for:
1. **Different language**: Same term means different things
2. **Different models**: Same concept has different attributes/behavior
3. **Different teams**: Natural organizational boundaries
4. **Different lifecycles**: Entities created/destroyed at different times
5. **Different rate of change**: Some areas evolve faster than others
**From vision/manifesto:**
- Identify personas → each persona likely interacts with different contexts
- Identify core domain concepts → group related concepts into contexts
- Identify capabilities → capabilities often align with contexts
**From existing code:**
- Look for packages/modules that cluster related concepts
- Identify seams where code is loosely coupled
- Look for translation layers between subsystems
- Identify areas where same terms mean different things
### Context Boundaries
**Good boundaries:**
- Clear interfaces between contexts
- Each context owns its data
- Contexts communicate via events or APIs
- Minimal coupling between contexts
**Bad boundaries:**
- Shared database tables across contexts
- Direct object references across contexts
- Mixed concerns within a context
### Common Context Patterns
| Pattern | Description | Example |
|---------|-------------|---------|
| **Core Domain** | Your unique competitive advantage | Custom business logic |
| **Supporting Subdomain** | Necessary but not differentiating | User management |
| **Generic Subdomain** | Common problems, use off-the-shelf | Email sending, file storage |
## Tactical DDD: Building Blocks
### Aggregates
An **aggregate** is a cluster of entities and value objects treated as a unit for data changes.
**Rules:**
- One entity is the **aggregate root** (only entity referenced from outside)
- All changes go through the root
- Enforce business invariants within the aggregate
- Keep aggregates small (2-3 entities max when possible)
**Example:**
```
Order (root)
├── OrderLine
├── ShippingAddress
└── Payment
```
External code only references `Order`, never `OrderLine` directly.
**Identifying aggregates:**
- What entities always change together?
- What invariants must be enforced?
- What is the transactional boundary?
### Commands
**Commands** represent intent to change state. Named with imperative verbs.
**Format:** `[Verb][AggregateRoot]` or `[AggregateRoot][Verb]`
**Examples:**
- `PlaceOrder` or `OrderPlace`
- `CancelSubscription` or `SubscriptionCancel`
- `ApproveInvoice` or `InvoiceApprove`
**Commands:**
- Are handled by the aggregate root
- Either succeed completely or fail
- Can be rejected (return error)
- Represent user intent or system action
### Events
**Events** represent facts that happened in the past. Named in past tense.
**Format:** `[AggregateRoot][PastVerb]` or `[Something]Happened`
**Examples:**
- `OrderPlaced`
- `SubscriptionCancelled`
- `InvoiceApproved`
- `PaymentFailed`
**Events:**
- Are immutable (already happened)
- Can be published to other contexts
- Enable eventual consistency
- Create audit trail
### Value Objects
**Value Objects** are immutable objects defined by their attributes, not identity.
**Examples:**
- `Money` (amount + currency)
- `EmailAddress`
- `DateRange`
- `Address`
**Characteristics:**
- No identity (two with same values are equal)
- Immutable (cannot change, create new instance)
- Can contain validation logic
- Can contain behavior
**When to use:**
- Concept has no lifecycle (no create/update/delete)
- Equality is based on attributes, not identity
- Can be shared/reused
### Entities
**Entities** have identity that persists over time, even if attributes change.
**Examples:**
- `User` (ID remains same even if name/email changes)
- `Order` (ID remains same through lifecycle)
- `Product` (ID remains same even if price changes)
**Characteristics:**
- Has unique identifier
- Can change over time
- Identity matters more than attributes
## Mapping Features to DDD Patterns
### Process
For each feature from vision:
1. **Identify the bounded context**: Which context does this belong to?
2. **Identify the aggregate(s)**: What entities/value objects are involved?
3. **Identify commands**: What actions can users/systems take?
4. **Identify events**: What facts should be recorded when commands succeed?
5. **Identify value objects**: What concepts are attribute-defined, not identity-defined?
### Example: "User can place an order"
**Bounded Context:** Sales
**Aggregate:** `Order` (root)
- `OrderLine` (entity)
- `ShippingAddress` (value object)
- `Money` (value object)
**Commands:**
- `PlaceOrder`
- `AddOrderLine`
- `RemoveOrderLine`
- `UpdateShippingAddress`
**Events:**
- `OrderPlaced`
- `OrderLineAdded`
- `OrderLineRemoved`
- `ShippingAddressUpdated`
**Value Objects:**
- `Money` (amount, currency)
- `Address` (street, city, zip, country)
- `Quantity`
## Refactoring to DDD
When existing code doesn't follow DDD patterns:
### Identify Misalignments
**Anemic domain model:**
- Entities with only getters/setters
- Business logic in services, not entities
- **Fix:** Move behavior into aggregates
**God objects:**
- One entity doing too much
- **Fix:** Split into multiple aggregates or value objects
**Context leakage:**
- Same model shared across contexts
- **Fix:** Create context-specific models with translation layers
**Missing boundaries:**
- Everything in one module/package
- **Fix:** Identify bounded contexts, separate into modules
### Refactoring Strategies
**Extract bounded context:**
```markdown
As a developer, I want to extract [Context] into a separate module,
so that it has clear boundaries and can evolve independently
```
**Extract aggregate:**
```markdown
As a developer, I want to extract [Aggregate] from [GodObject],
so that it enforces its own invariants
```
**Introduce value object:**
```markdown
As a developer, I want to replace [primitive] with [ValueObject],
so that validation is centralized and the domain model is clearer
```
**Introduce event:**
```markdown
As a developer, I want to publish [Event] when [Command] succeeds,
so that other contexts can react to state changes
```
## Anti-Patterns
**Avoid:**
- Aggregates spanning multiple bounded contexts
- Shared mutable state across contexts
- Direct database access across contexts
- Aggregates with dozens of entities (too large)
- Value objects with identity
- Commands without clear aggregate ownership
- Events that imply future actions (use commands)
## Tips
- Start with strategic DDD (bounded contexts) before tactical patterns
- Bounded contexts align with team/organizational boundaries
- Keep aggregates small (single entity when possible)
- Use events for cross-context communication
- Value objects make impossible states impossible
- Refactor incrementally - don't rewrite everything at once

80
skills/gitea/SKILL.md
View File

@@ -1,21 +1,51 @@
---
name: gitea
model: haiku
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.
user-invocable: false
---
# Gitea CLI (tea)
Command-line interface for Gitea repositories. Use `tea` for issue/PR management in Gitea instances.
Command-line interface for interacting with Gitea repositories.
**Setup required?** See [reference/setup.md](reference/setup.md) for installation and authentication.
## Installation
```bash
brew install tea
```
## Authentication
The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
```bash
tea logins add # Interactive login
tea logins add --url <url> --token <token> --name <name> # Non-interactive
tea logins list # Show configured logins
tea logins default <name> # Set default login
```
## Configuration
Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
To avoid needing `--login` on every command, set defaults:
```yaml
preferences:
editor: false
flag_defaults:
remote: origin
login: git.flowmade.one
```
## Repository Detection
`tea` automatically detects the repository from git remotes when run inside a git repository. Use `--remote <name>` to specify which remote to use.
## Issues
## Common Commands
### Issues
```bash
# List issues
@@ -50,7 +80,7 @@ tea issues deps add 5 owner/repo#3 # Cross-repo dependency
tea issues deps remove <issue> <blocker> # Remove a dependency
```
## Pull Requests
### Pull Requests
```bash
# List PRs
@@ -90,7 +120,15 @@ tea pulls merge <number> --style rebase-merge # Rebase then merge
tea pulls clean <number> # Delete local & remote branch
```
## Comments
### Repository
```bash
tea repos # List repos
tea repos <owner>/<repo> # Repository info
tea clone <owner>/<repo> # Clone repository
```
### Comments
```bash
# Add comment to issue or PR
@@ -106,15 +144,7 @@ tea comment 3 "## Review Summary
> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
## Repository
```bash
tea repos # List repos
tea repos <owner>/<repo> # Repository info
tea clone <owner>/<repo> # Clone repository
```
## Notifications
### Notifications
```bash
tea notifications # List notifications
@@ -148,6 +178,22 @@ tea issues -r owner/repo # Specify repo directly
- Use `--remote gitea` when you have multiple remotes (e.g., origin + gitea)
- The `tea pulls checkout` command is handy for reviewing PRs locally
## Advanced Topics
## Actions / CI
- **CI/Actions debugging**: See [reference/actions-ci.md](reference/actions-ci.md)
```bash
# List workflow runs
tea actions runs # List all workflow runs
tea actions runs -o json # JSON output for parsing
# List jobs for a run
tea actions jobs <run-id> # Show jobs for a specific run
tea actions jobs <run-id> -o json # JSON output
# Get job logs
tea actions logs <job-id> # Display logs for a job
# Full workflow: find failed job logs
tea actions runs # Find the run ID
tea actions jobs <run-id> # Find the job ID
tea actions logs <job-id> # View the logs
```

45
skills/gitea/reference/actions-ci.md
View File

@@ -1,45 +0,0 @@
# Gitea Actions / CI
Commands for debugging CI/Actions workflow failures in Gitea.
## Workflow Runs
```bash
# List workflow runs
tea actions runs # List all workflow runs
tea actions runs -o json # JSON output for parsing
```
## Jobs
```bash
# List jobs for a run
tea actions jobs <run-id> # Show jobs for a specific run
tea actions jobs <run-id> -o json # JSON output
```
## Logs
```bash
# Get job logs
tea actions logs <job-id> # Display logs for a job
```
## Full Workflow: Find Failed Job Logs
```bash
# 1. Find the run ID
tea actions runs
# 2. Find the job ID from that run
tea actions jobs <run-id>
# 3. View the logs
tea actions logs <job-id>
```
## Tips
- Use `-o json` with runs/jobs for programmatic parsing
- Run IDs and Job IDs are shown in the output of the respective commands
- Logs are displayed directly to stdout (can pipe to `grep` or save to file)

49
skills/gitea/reference/setup.md
View File

@@ -1,49 +0,0 @@
# Gitea CLI Setup
One-time installation and authentication setup for `tea` CLI.
## Installation
```bash
brew install tea
```
## Authentication
The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
```bash
tea logins add # Interactive login
tea logins add --url <url> --token <token> --name <name> # Non-interactive
tea logins list # Show configured logins
tea logins default <name> # Set default login
```
## Configuration
Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
To avoid needing `--login` on every command, set defaults:
```yaml
preferences:
editor: false
flag_defaults:
remote: origin
login: git.flowmade.one
```
## Example: Flowmade One Setup
```bash
# Install
brew install tea
# Add login (get token from https://git.flowmade.one/user/settings/applications)
tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>
# Set as default
tea logins default flowmade
```
Now `tea` commands will automatically use the flowmade login when run in a repository with a git.flowmade.one remote.

162
skills/issue-writing/SKILL.md
View File

@@ -1,25 +1,25 @@
---
name: issue-writing
description: >
Write clear, actionable issues with user stories, vertical slices, and acceptance
criteria. Use when creating issues, writing bug reports, feature requests, or when
the user needs help structuring an issue.
description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
user-invocable: false
---
# Issue Writing
How to write clear, actionable issues that deliver user value.
How to write clear, actionable issues.
## Primary Format: User Story
## Issue Structure
Frame issues as user capabilities, not technical tasks:
### Title
- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
- Be specific: "Add user authentication" not "Auth stuff"
- Keep under 60 characters when possible
### Description
```markdown
Title: As a [persona], I want to [action], so that [benefit]
## User Story
As a [persona], I want to [action], so that [benefit]
## Summary
One paragraph explaining what and why.
## Acceptance Criteria
- [ ] Specific, testable requirement
@@ -33,22 +33,20 @@ Additional background, links, or references.
Implementation hints or constraints.
```
**Example:**
## Writing Acceptance Criteria
Good criteria are:
- **Specific**: "User sees error message" not "Handle errors"
- **Testable**: Can verify pass/fail
- **User-focused**: What the user experiences
- **Independent**: Each stands alone
Examples:
```markdown
Title: As a domain expert, I want to save my diagram, so that I can resume work later
## User Story
As a domain expert, I want to save my diagram to the cloud, so that I can resume
work later from any device.
## Acceptance Criteria
- [ ] User can click "Save" button in toolbar
- [ ] Diagram persists to cloud storage
- [ ] User sees confirmation message on successful save
- [ ] Saved diagram appears in recent files list
## Context
Users currently lose work when closing the browser. This is the #1 requested feature.
- [ ] Login form validates email format before submission
- [ ] Invalid credentials show "Invalid email or password" message
- [ ] Successful login redirects to dashboard
- [ ] Session persists across browser refresh
```
## Vertical Slices
@@ -66,61 +64,28 @@ Before writing an issue, ask: **Can a user demo or test this independently?**
| Good (Vertical) | Bad (Horizontal) |
|-----------------|------------------|
| "As a user, I want to save my diagram" | "Add persistence layer" |
| "As a user, I want to see errors when login fails" | "Add error handling" |
| "As a domain expert, I want to list orders" | "Add query syntax to ADL" |
| "User can save and reload diagram" | "Add persistence layer" |
| "Show error when login fails" | "Add error handling" |
| "Domain expert can list orders" | "Add query syntax to ADL" |
The technical work is the same, but vertical slices make success criteria clear and deliver demonstrable value.
### Writing User-Focused Issues
## Writing User Stories
### Format
```
As a [persona], I want [capability], so that [benefit]
```
**Persona:** From manifesto or product vision (e.g., domain expert, developer, product owner)
**Capability:** What the user can do (not how it's implemented)
**Benefit:** Why this matters to the user
### Examples
Frame issues around user capabilities:
```markdown
✓ As a developer, I want to run tests locally, so that I can verify changes before pushing
✓ As a product owner, I want to view open issues, so that I can prioritize work
✓ As a domain expert, I want to export my model as JSON, so that I can share it with my team
# Bad: Technical task
Title: Add email service integration
✗ As a developer, I want a test runner (missing benefit)
✗ I want to add authentication (missing persona and benefit)
✗ As a user, I want the system to be fast (not specific/testable)
# Good: User capability
Title: User receives confirmation email after signup
```
## Acceptance Criteria
The technical work is the same, but the good title makes success criteria clear.
Good criteria are:
- **Specific**: "User sees error message" not "Handle errors"
- **Testable**: Can verify pass/fail
- **User-focused**: What the user experiences
- **Independent**: Each stands alone
**Examples:**
```markdown
- [ ] Login form validates email format before submission
- [ ] Invalid credentials show "Invalid email or password" message
- [ ] Successful login redirects to dashboard
- [ ] Session persists across browser refresh
```
## Alternative Formats
## Issue Types
### Bug Report
```markdown
Title: Fix [specific problem] in [area]
## Summary
Description of the bug.
@@ -139,48 +104,37 @@ What happens instead.
- Browser/OS/Version
```
### Technical Task
Use sparingly - prefer user stories when possible.
### Feature Request
```markdown
Title: [Action] [component/area]
## Summary
What technical work needs to be done and why.
What feature and why it's valuable.
## Acceptance Criteria
- [ ] ...
## User Story (optional)
As a [role], I want [capability] so that [benefit].
```
### Technical Task
```markdown
## Summary
What technical work needs to be done.
## Scope
- Include: ...
- Exclude: ...
## Acceptance Criteria
- [ ] Measurable technical outcome
- [ ] Another measurable outcome
```
## Issue Sizing
Issues should be **small enough to complete in 1-3 days**.
**Too large?** Split into smaller vertical slices:
```markdown
# Too large
As a user, I want full authentication, so that my data is secure
# Better: Split into slices
1. As a user, I want to register with email/password, so that I can create an account
2. As a user, I want to log in with my credentials, so that I can access my data
3. As a user, I want to reset my password, so that I can regain access if I forget it
- [ ] ...
```
## Labels
Use labels to categorize:
- Type: `bug`, `feature`, `enhancement`, `refactor`
- Priority: `priority/high`, `priority/medium`, `priority/low`
- Component: Project-specific (e.g., `auth`, `api`, `ui`)
- DDD: `bounded-context/[name]`, `aggregate`, `command`, `event` (when applicable)
- `bug`, `feature`, `enhancement`, `refactor`
- `priority/high`, `priority/low`
- Component labels specific to project
## Dependencies
@@ -200,13 +154,3 @@ Identify and link dependencies when creating issues:
```
This creates a formal dependency graph that tools can query.
## Anti-Patterns
**Avoid:**
- Generic titles: "Fix bugs", "Improve performance"
- Technical jargon without context: "Refactor service layer"
- Missing acceptance criteria
- Horizontal slices: "Build API", "Add database tables"
- Vague criteria: "Make it better", "Improve UX"
- Issues too large to complete in a sprint

4
old/skills/repo-conventions/SKILL.md → skills/repo-conventions/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: repo-conventions
model: haiku
description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
user-invocable: false
---
@@ -17,7 +16,8 @@ All product repos should follow this structure relative to the architecture repo
org/
├── architecture/ # Organizational source of truth
│ ├── manifesto.md # Organization identity and beliefs
│ ├── skills/ # User-invocable and background skills
│ ├── commands/ # Claude Code workflows
│ ├── skills/ # Knowledge modules
│ └── agents/ # Subtask handlers
├── product-a/ # Product repository
│ ├── vision.md # Product vision (extends manifesto)

1
old/skills/roadmap-planning/SKILL.md → skills/roadmap-planning/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: roadmap-planning
model: haiku
description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
user-invocable: false
---

1
old/skills/software-architecture/SKILL.md → skills/software-architecture/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: software-architecture
model: haiku
description: >
Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
Use when implementing features, reviewing code, planning issues, refining architecture,

1
old/skills/vision-management/SKILL.md → skills/vision-management/SKILL.md
View File

@@ -1,6 +1,5 @@
---
name: vision-management
model: haiku
description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
user-invocable: false
---