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

Add validation and interactive guidance to /create-capability

Browse Source 
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>
This commit is contained in:
Hugo Nijhuis
2026-01-10 23:52:34 +01:00
parent a4c09b8411
commit e0fa7377ec
1 changed files with 216 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
commands/create-capability.md
View File

@@ -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: <description>
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 `<arg>` 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/<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:
```
## 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/<name>/SKILL.md`
- `commands/<name>.md`
- `agents/<name>/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/<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
- 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