From e0fa7377ece791c227e2dc8ceac406a4ec9629bc Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 10 Jan 2026 23:52:34 +0100 Subject: [PATCH] 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 --- commands/create-capability.md | 299 ++++++++++++++++++++++++---------- 1 file changed, 216 insertions(+), 83 deletions(-) diff --git a/commands/create-capability.md b/commands/create-capability.md index 4774a5d..2e9f80e 100644 --- a/commands/create-capability.md +++ b/commands/create-capability.md @@ -1,123 +1,256 @@ --- -description: Create a new capability (skill, command, agent, or a cohesive set) for the architecture repository. +description: Create new capabilities (skills, commands, agents) with validation and guided design decisions. argument-hint: +model: sonnet --- # Create Capability @~/.claude/skills/capability-writing/SKILL.md -Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + command + agent). +Create new capabilities for the architecture repository with validation and interactive guidance. ## 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? +### Phase 1: Understand Intent -2. **Determine components needed**: Based on the description, recommend which components: +1. **Parse the description** from `$1` or ask for one: + - "What capability do you want to add? Describe what it should do." - | 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 | +2. **Ask clarifying questions** to determine component type: - Present recommendation with reasoning: - ``` - ## Recommended Components for: $1 + | 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? | - Based on your description, I recommend: - - **Skill**: `name` - [why this knowledge is needed] - - **Command**: `/name` - [what user action this enables] - - **Agent**: `name` - [why isolation/specialization is needed] (optional) +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 - Reasoning: [explain why this combination fits the need] - ``` +### Phase 2: Gather Details -3. **Gather information**: For each recommended component, ask: - - **For all components:** - - Name (kebab-case, descriptive) - - Description (one-line summary) +4. **Collect information for each component**: **For Skills:** - - What domain/knowledge does this cover? - - What are the key concepts to teach? - - What patterns or templates should it include? + - Name (kebab-case): skill name matching directory + - Description: what it teaches + trigger conditions + - Core sections to include **For Commands:** - - What triggers this workflow? - - What are the key steps? - - What approval points are needed? - - What skills should it reference? + - Name (kebab-case): verb-phrase action name + - Description: one-line summary + - Arguments: required `` and optional `[arg]` + - Skills to reference **For Agents:** - - What specialized role does this fill? - - What skills does it need? - - Should it be read-only (no Edit/Write)? + - Name (kebab-case): role-based specialist name + - Description: what it does + when to spawn + - Skills it needs + - Tool restrictions (read-only?) -4. **Select appropriate models**: +### Phase 3: Model Selection - | Model | Use For | - |-------|---------| - | `haiku` | Simple fetch/display commands, formatting tasks | - | `sonnet` | Most commands and agents (default) | - | `opus` | Deep reasoning, architectural analysis, complex judgment | +5. **Recommend appropriate models** with explanation: - For each component, recommend a model with reasoning. + | 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 | -5. **Generate files**: Create content using templates from capability-writing skill + 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" - Ensure proper inter-references: - - Command references skill via `@~/.claude/skills/name/SKILL.md` - - Agent lists skills in `skills:` frontmatter (names only, not paths) - - Command spawns agent via Task tool if agent is part of the set +### 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//`, `commands/`, `agents//` | + | 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: ``` - ## Generated Files + ## Validation Results - ### skills/name/SKILL.md - [full content] + [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 - ### commands/name.md - [full content] - - ### agents/name/AGENT.md (if applicable) - [full content] - - Ready to create these files? + Proceed with warnings? (y/n) ``` -7. **Create files** in correct locations after approval: - - `skills//SKILL.md` - - `commands/.md` - - `agents//AGENT.md` +10. **Show file preview** with full content: -8. **Report success**: - ``` - ## Capability Created: name + ``` + ## Files to Create - Files created: - - skills/name/SKILL.md - - commands/name.md - - agents/name/AGENT.md (if applicable) + ### skills/migration-review/SKILL.md - Next steps: - 1. Run `make install` to symlink to ~/.claude/ - 2. Test with: /name (for commands) - 3. Skills will auto-activate based on context - ``` + ```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/ + mkdir -p agents/ + ``` + + If directory creation fails, report the error and stop. + +13. **Write files** to correct locations: + - `skills//SKILL.md` + - `commands/.md` + - `agents//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 -- Follow all conventions from capability-writing skill -- Reference existing skills rather than duplicating knowledge -- Keep components focused - split if scope is too broad -- Commands should have approval checkpoints before significant actions -- Default to `sonnet` model unless there's a clear reason for haiku/opus -- Skills should have descriptive `description` fields for auto-activation +- 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 -- 2.49.1