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

refactor: migrate commands to user-invocable skills

Browse Source 
Claude Code has unified commands into skills with the user-invocable
frontmatter field. This migration:

- Converts 20 commands to skills with user-invocable: true
- Consolidates docs into single writing-capabilities.md
- Rewrites capability-writing skill for unified model
- Updates CLAUDE.md, Makefile, and other references
- Removes commands/ directory

Skills now have two types:
- user-invocable: true - workflows users trigger with /name
- user-invocable: false - background knowledge auto-loaded

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-11 16:39:46 +01:00
parent 3d9933fd52
commit 7406517cd9
29 changed files with 771 additions and 2229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -2,23 +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 + command + agent).
Use when creating new skills, commands, or agents, or when extending the
A capability is a cohesive set of components (skill + agent).
Use when creating new skills, agents, or extending the
AI workflow system. Includes templates, design guidance, and conventions.
user-invocable: false
---
# Capability Writing
How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together.
How to design and create capabilities for the architecture repository. A capability may be a single component or a cohesive set (skill + agent).
## Component Overview
| Component | Location | Purpose | Example |
|-----------|----------|---------|---------|
| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |
| **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 |
## When to Use Each Component
@@ -28,36 +28,36 @@ How to design and create capabilities for the architecture repository. A capabil
Start here: What do you need?
|
+--> Just knowledge to apply automatically?
| --> Skill only
| --> Background skill (user-invocable: false)
|
+--> User-initiated workflow using existing knowledge?
| --> Command (reference skills via @)
+--> User-initiated workflow?
| --> User-invocable skill (user-invocable: true)
|
+--> Complex isolated work needing focused context?
| --> Command + Agent (agent uses skills)
| --> User-invocable skill + Agent
|
+--> New domain expertise + workflow + isolated work?
--> Full capability (all three)
--> Full capability (background skill + user-invocable skill + agent)
```
### Decision Matrix
| Need | Component | Example |
|------|-----------|---------|
| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
| User-invoked workflow | Command | /work-issue, /dashboard |
| Knowledge Claude applies automatically | Background skill | gitea, issue-writing |
| User-invoked workflow | User-invocable skill | /work-issue, /dashboard |
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
| All three working together | Full capability | arch-review (skill + command + agent) |
| All three working together | Full capability | architecture review |
### Signs You Need Each Component
**Create a Skill when:**
**Create a Background 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
- Multiple user-invocable skills need the same knowledge
- There is a clear domain that doesn't fit existing skills
**Create a Command when:**
**Create a User-Invocable Skill when:**
- Same workflow is used multiple times
- User explicitly triggers the action
- Approval checkpoints are needed
@@ -71,7 +71,47 @@ Start here: What do you need?
## Component Templates
### Skill Template
### User-Invocable Skill Template
Location: `skills/<name>/SKILL.md`
```yaml
---
name: skill-name
description: >
What this skill does and when to use it.
Use when [trigger conditions] or when user says /skill-name.
model: haiku
argument-hint: <required> [optional]
user-invocable: true
---
# Skill Title
@~/.claude/skills/relevant-skill/SKILL.md
Brief intro if needed.
1. **First step**: What to do
2. **Second step**: What to do next
3. **Ask for approval** before significant actions
4. **Execute** the approved actions
5. **Present results** with links and summary
```
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to use (max 1024 chars) |
| `user-invocable` | Yes | Set `true` for user-triggered workflows |
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
| `model` | No | `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
### Background Skill Template
Location: `skills/<name>/SKILL.md`
@@ -80,8 +120,7 @@ Location: `skills/<name>/SKILL.md`
name: skill-name
description: >
What this skill teaches and when to use it.
Include trigger conditions in description (not body).
List specific capabilities users would mention.
Include trigger conditions in description.
user-invocable: false
---
@@ -114,49 +153,6 @@ Document pitfalls to avoid.
Quick-reference tables, checklists, or commands.
```
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to use (max 1024 chars) |
| `user-invocable` | No | Set `false` for reference-only skills |
| `model` | No | Specific model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
### Command Template
Location: `commands/<name>.md`
```yaml
---
description: What this command does (one-line summary)
argument-hint: <required> [optional]
model: haiku
---
# Command Title
@~/.claude/skills/relevant-skill/SKILL.md
1. **First step**: What to do
2. **Second step**: What to do next
3. **Ask for approval** before significant actions
4. **Execute** the approved actions
5. **Present results** with links and summary
```
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | One-line summary for help/listings |
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
| `model` | No | Override model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
### Agent Template
Location: `agents/<name>/AGENT.md`
@@ -165,7 +161,7 @@ Location: `agents/<name>/AGENT.md`
---
name: agent-name
description: What this agent does and when to spawn it
model: haiku
model: sonnet
skills: skill1, skill2
disallowedTools:
- Edit
@@ -210,13 +206,13 @@ Describe expected output structure.
| 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 |
| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
### Decision Criteria
- **Start with `sonnet`** - handles most tasks well
- **Use `haiku` for volume** - speed and cost matter at scale
- **Start with `haiku`** for simple display/fetch workflows
- **Use `sonnet`** for most skills and agents (default choice)
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
- **Consider the stakes** - higher consequence tasks warrant more capable models
@@ -226,31 +222,26 @@ Describe expected output structure.
| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
| 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`
**Skills:** Name after the domain, knowledge area, or action
- Good: `gitea`, `issue-writing`, `work-issue`, `dashboard`
- Bad: `utils`, `helpers`, `misc`
**Commands:** Use verb or verb-phrase (actions)
- Good: `work-issue`, `review-pr`, `create-issue`
- Bad: `issue-work`, `pr-review`, `issue`
**Agents:** Name by role or persona (recognizable specialist)
- Good: `code-reviewer`, `issue-worker`, `software-architect`
- Bad: `helper`, `do-stuff`, `agent1`
## Referencing Skills
### In Commands
### In User-Invocable Skills
Use the `@` file reference syntax to guarantee skill content is loaded:
Use the `@` file reference syntax to guarantee background skill content is loaded:
```markdown
@~/.claude/skills/gitea/SKILL.md
@@ -274,7 +265,7 @@ The agent runtime loads these skills automatically.
## Common Patterns
### Approval Workflow (Commands)
### Approval Workflow (User-Invocable Skills)
Always ask before significant actions:
@@ -284,7 +275,7 @@ Always ask before significant actions:
6. **Present summary** with links
```
### Conditional Behavior (Commands)
### Conditional Behavior (User-Invocable Skills)
Handle optional arguments with mode switching:
@@ -298,7 +289,7 @@ Handle optional arguments with mode switching:
2. Process each
```
### Spawning Agents from Commands
### Spawning Agents from Skills
Delegate complex subtasks:
@@ -323,7 +314,7 @@ disallowedTools:
### Overly Broad Components
**Bad:** One skill/command/agent that does everything
**Bad:** One skill/agent that does everything
```markdown
# Project Management
Handles issues, PRs, releases, documentation, deployment...
@@ -383,37 +374,32 @@ Use `tea issues create --title "..." --description "..."`
## Detailed Documentation
For comprehensive guides, see the `docs/` directory:
For comprehensive guides, see:
- `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
- `docs/writing-capabilities.md` - Complete guide covering skills and agents
## Checklists
### Before Creating a Skill
### Before Creating a User-Invocable Skill
- [ ] Workflow is used multiple times
- [ ] User explicitly triggers it (not automatic)
- [ ] Clear start and end points
- [ ] Frontmatter has `user-invocable: true`
- [ ] Description includes "Use when... or when user says /skill-name"
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
- [ ] Approval checkpoints before significant actions
- [ ] File at `skills/<name>/SKILL.md`
### Before Creating a Background Skill
- [ ] Knowledge is used in multiple places (not just once)
- [ ] Existing skills do not already cover this domain
- [ ] Content is specific and actionable (not generic)
- [ ] Frontmatter has descriptive `description` with trigger terms
- [ ] Frontmatter has `user-invocable: false`
- [ ] Description includes trigger terms
- [ ] File at `skills/<name>/SKILL.md`
### 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