Configure model settings for commands, agents, and skills

Set explicit model preferences to optimize for speed vs capability: - haiku: 11 commands, 2 agents (issue-worker, pr-fixer), 10 skills Fast execution for straightforward tasks - sonnet: 4 commands (groom, improve, plan-issues, review-pr), 1 agent (code-reviewer) Better judgment for analysis and review tasks - opus: 2 commands (arch-refine-issue, arch-review-repo), 1 agent (software-architect) Deep reasoning for architectural analysis Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-11 00:06:53 +01:00
28 changed files with 111 additions and 218 deletions
--- a/agents/issue-worker/agent.md
+++ b/agents/issue-worker/agent.md
@@ -1,5 +1,6 @@
 ---
 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
--- a/agents/pr-fixer/agent.md
+++ b/agents/pr-fixer/agent.md
@@ -1,5 +1,6 @@
 ---
 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
--- a/commands/arch-refine-issue.md
+++ b/commands/arch-refine-issue.md
@@ -1,5 +1,6 @@
 ---
 description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
 model: opus
 argument-hint: <issue-number>
 ---
--- a/commands/arch-review-repo.md
+++ b/commands/arch-review-repo.md
@@ -1,5 +1,6 @@
 ---
 description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
 model: opus
 argument-hint:
 context: fork
 ---
--- a/commands/create-capability.md
+++ b/commands/create-capability.md
@@ -1,256 +1,123 @@
 ---
-description: Create new capabilities (skills, commands, agents) with validation and guided design decisions.
+description: Create a new capability (skill, command, agent, or a cohesive set) for the architecture repository.
 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.
+Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + command + agent).
 ## Process
-### Phase 1: Understand Intent
+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?
-1. **Parse the description** from `$1` or ask for one:
+2. **Determine components needed**: Based on the description, recommend which components:
   - "What capability do you want to add? Describe what it should do."
-2. **Ask clarifying questions** to determine component type:
+   | Pattern | When to Use |
   |---------|-------------|
   | Skill only | Knowledge to apply automatically (reused across commands) |
   | Command only | User-invoked workflow using existing skills |
   | Command + Skill | New knowledge + workflow to use it |
   | Command + Agent | Workflow with isolated worker for complex subtasks |
   | Full set | New domain expertise + workflow + isolated work |
-   | Question | Purpose |
+   Present recommendation with reasoning:
-   |----------|---------|
+   ```
-   | "Will this knowledge apply automatically, or is it user-invoked?" | Skill vs Command |
+   ## Recommended Components for: $1
   | "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:
+   Based on your description, I recommend:
-   - **Skill only**: Knowledge Claude applies automatically
+   - **Skill**: `name` - [why this knowledge is needed]
-   - **Command only**: Workflow using existing skills
+   - **Command**: `/name` - [what user action this enables]
-   - **Command + Skill**: New knowledge + workflow
+   - **Agent**: `name` - [why isolation/specialization is needed] (optional)
   - **Command + Agent**: Workflow with isolated worker
   - **Full set**: Skill + Command + Agent
-### Phase 2: Gather Details
+   Reasoning: [explain why this combination fits the need]
   ```
-4. **Collect information for each component**:
+3. **Gather information**: For each recommended component, ask:
   **For all components:**
   - Name (kebab-case, descriptive)
   - Description (one-line summary)
   **For Skills:**
-   - Name (kebab-case): skill name matching directory
+   - What domain/knowledge does this cover?
-   - Description: what it teaches + trigger conditions
+   - What are the key concepts to teach?
-   - Core sections to include
+   - What patterns or templates should it include?
   **For Commands:**
-   - Name (kebab-case): verb-phrase action name
+   - What triggers this workflow?
-   - Description: one-line summary
+   - What are the key steps?
-   - Arguments: required `<arg>` and optional `[arg]`
+   - What approval points are needed?
-   - Skills to reference
+   - What skills should it reference?
   **For Agents:**
-   - Name (kebab-case): role-based specialist name
+   - What specialized role does this fill?
-   - Description: what it does + when to spawn
+   - What skills does it need?
-   - Skills it needs
+   - Should it be read-only (no Edit/Write)?
   - Tool restrictions (read-only?)
-### Phase 3: Model Selection
+4. **Select appropriate models**:
-5. **Recommend appropriate models** with explanation:
+   | Model | Use For |
   |-------|---------|
   | `haiku` | Simple fetch/display commands, formatting tasks |
   | `sonnet` | Most commands and agents (default) |
   | `opus` | Deep reasoning, architectural analysis, complex judgment |
-   | Capability Pattern | Model | Rationale |
+   For each component, recommend a model with reasoning.
   |-------------------|-------|-----------|
   | 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:
+5. **Generate files**: Create content using templates from capability-writing skill
   - "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
+   Ensure proper inter-references:
-
+   - Command references skill via `@~/.claude/skills/name/SKILL.md`
-6. **Generate file content** using templates from capability-writing skill
+   - Agent lists skills in `skills:` frontmatter (names only, not paths)
-
+   - Command spawns agent via Task tool if agent is part of the set
 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**:
 6. **Present for approval**: Show all generated files with their full content:
   ```
-   ## Validation Results
+   ## Generated Files
-   [PASS] Frontmatter: All required fields present
+   ### skills/name/SKILL.md
-   [PASS] Model: sonnet is valid
+   [full content]
   [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)
+   ### commands/name.md
   [full content]
   ### agents/name/AGENT.md (if applicable)
   [full content]
   Ready to create these files?
   ```
-10. **Show file preview** with full content:
+7. **Create files** in correct locations after approval:
   - `skills/<name>/SKILL.md`
   - `commands/<name>.md`
   - `agents/<name>/AGENT.md`
-    ```
+8. **Report success**:
-    ## Files to Create
+   ```
   ## Capability Created: name
-    ### skills/migration-review/SKILL.md
+   Files created:
   - skills/name/SKILL.md
   - commands/name.md
   - agents/name/AGENT.md (if applicable)
-    ```yaml
+   Next steps:
-    ---
+   1. Run `make install` to symlink to ~/.claude/
-    name: migration-review
+   2. Test with: /name (for commands)
-    description: >
+   3. Skills will auto-activate based on context
-      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
+- Follow all conventions from capability-writing skill
- Show warnings but allow override with explicit confirmation
+- Reference existing skills rather than duplicating knowledge
- Validate skill references exist before creating dependent components
+- Keep components focused - split if scope is too broad
- Suggest related existing skills that could be referenced
+- Commands should have approval checkpoints before significant actions
- Keep generated content minimal - users can expand after testing
+- Default to `sonnet` model unless there's a clear reason for haiku/opus
 - Skills should have descriptive `description` fields for auto-activation
--- a/commands/create-issue.md
+++ b/commands/create-issue.md
@@ -1,5 +1,6 @@
 ---
 description: Create a new Gitea issue. Can create single issues or batch create from a plan.
 model: haiku
 argument-hint: [title] or "batch"
 ---
--- a/commands/create-repo.md
+++ b/commands/create-repo.md
@@ -1,5 +1,6 @@
 ---
 description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
 model: haiku
 argument-hint: <repo-name>
 context: fork
 ---
--- a/commands/groom.md
+++ b/commands/groom.md
@@ -1,5 +1,6 @@
 ---
 description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
 model: sonnet
 argument-hint: [issue-number]
 ---
--- a/commands/improve.md
+++ b/commands/improve.md
@@ -1,5 +1,6 @@
 ---
 description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
 model: sonnet
 argument-hint:
 context: fork
 ---
--- a/commands/manifesto.md
+++ b/commands/manifesto.md
@@ -1,5 +1,6 @@
 ---
 description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
 model: haiku
 argument-hint:
 ---
--- a/commands/plan-issues.md
+++ b/commands/plan-issues.md
@@ -1,5 +1,6 @@
 ---
 description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
 model: sonnet
 argument-hint: <feature-description>
 context: fork
 ---
--- a/commands/retro.md
+++ b/commands/retro.md
@@ -1,5 +1,6 @@
 ---
 description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 model: haiku
 argument-hint: [task-description]
 ---
--- a/commands/review-pr.md
+++ b/commands/review-pr.md
@@ -1,5 +1,6 @@
 ---
 description: Review a Gitea pull request. Fetches PR details, diff, and comments. Includes both code review and software architecture review.
 model: sonnet
 argument-hint: <pr-number>
 ---
--- a/commands/spawn-issues.md
+++ b/commands/spawn-issues.md
@@ -1,5 +1,6 @@
 ---
 allowed-tools: Bash, Task, Read, TaskOutput
 model: haiku
 description: Orchestrate parallel issue implementation with review cycles
 argument-hint: <issue-number> [<issue-number>...]
 ---
--- a/commands/spawn-pr-fixes.md
+++ b/commands/spawn-pr-fixes.md
@@ -1,5 +1,6 @@
 ---
 allowed-tools: Bash, Task, Read
 model: haiku
 description: Spawn parallel background agents to address PR review feedback
 argument-hint: [pr-number...]
 ---
--- a/commands/update-claude-md.md
+++ b/commands/update-claude-md.md
@@ -1,5 +1,6 @@
 ---
 description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
 model: haiku
 argument-hint:
 context: fork
 ---
--- a/commands/vision.md
+++ b/commands/vision.md
@@ -1,5 +1,6 @@
 ---
 description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
 model: haiku
 argument-hint: [goals]
 ---
--- a/commands/work-issue.md
+++ b/commands/work-issue.md
@@ -1,5 +1,6 @@
 ---
 description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
 model: haiku
 argument-hint: <issue-number>
 ---
--- a/skills/backlog-grooming/SKILL.md
+++ b/skills/backlog-grooming/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/capability-writing/SKILL.md
+++ b/skills/capability-writing/SKILL.md
@@ -133,7 +133,7 @@ Location: `commands/<name>.md`
 ---
 description: What this command does (one-line summary)
 argument-hint: <required> [optional]
-model: sonnet
+model: haiku
 ---
 # Command Title
@@ -165,7 +165,7 @@ Location: `agents/<name>/AGENT.md`
 ---
 name: agent-name
 description: What this agent does and when to spawn it
-model: sonnet
+model: haiku
 skills: skill1, skill2
 disallowedTools:
  - Edit
--- a/skills/claude-md-writing/SKILL.md
+++ b/skills/claude-md-writing/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/gitea/SKILL.md
+++ b/skills/gitea/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/issue-writing/SKILL.md
+++ b/skills/issue-writing/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/repo-conventions/SKILL.md
+++ b/skills/repo-conventions/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/roadmap-planning/SKILL.md
+++ b/skills/roadmap-planning/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---
--- a/skills/software-architecture/SKILL.md
+++ b/skills/software-architecture/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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,
--- a/skills/vision-management/SKILL.md
+++ b/skills/vision-management/SKILL.md
@@ -1,5 +1,6 @@
 ---
 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
 ---