[Issue #74] Create capability-writing skill with templates and design guidance #77

HugoNijhuis · 2026-01-10T14:43:06Z

HugoNijhuis commented

2026-01-10 14:43:06 +00:00

Summary

Creates a skill that teaches how to design and create capabilities for the architecture repository. A capability is a cohesive set of components (skill + command + agent) that work together.

Changes

Added skills/capability-writing/SKILL.md with:
- Component templates for skills, commands, and agents with frontmatter fields
- Decision tree and matrix for when to use each component
- Model selection guidance (haiku/sonnet/opus)
- Naming conventions (file and folder patterns)
- Skill referencing patterns (@ syntax for commands, skills list for agents)
- Common patterns (approval workflow, conditional behavior, spawning agents)
- Anti-patterns to avoid (overly broad components, vague instructions, god skills)
- References to detailed documentation in docs/ directory
- Checklists for creating each component type

Closes #74

## Summary Creates a skill that teaches how to design and create capabilities for the architecture repository. A capability is a cohesive set of components (skill + command + agent) that work together. ## Changes - Added `skills/capability-writing/SKILL.md` with: - Component templates for skills, commands, and agents with frontmatter fields - Decision tree and matrix for when to use each component - Model selection guidance (haiku/sonnet/opus) - Naming conventions (file and folder patterns) - Skill referencing patterns (@ syntax for commands, skills list for agents) - Common patterns (approval workflow, conditional behavior, spawning agents) - Anti-patterns to avoid (overly broad components, vague instructions, god skills) - References to detailed documentation in docs/ directory - Checklists for creating each component type Closes #74

HugoNijhuis added 1 commit 2026-01-10 14:43:07 +00:00

Add capability-writing skill with templates and design guidance c9a72bf1d3

Creates a skill that teaches how to design and create capabilities
(skill + command + agent combinations) for the architecture repository.

Includes:
- Component templates for skills, commands, and agents
- Decision tree and matrix for when to use each component
- Model selection guidance (haiku/sonnet/opus)
- Naming conventions and anti-patterns to avoid
- References to detailed documentation in docs/
- Checklists for creating each component type

Closes #74

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

HugoNijhuis commented

2026-01-10 14:44:21 +00:00

AI Code Review

This is an automated review generated by the code-reviewer agent.

Summary

Excellent addition to the architecture repository. This skill provides comprehensive, well-structured guidance for creating capabilities (skills, commands, and agents). The content is clear, practical, and follows established patterns in the codebase.

Findings

Code Quality

Well-organized structure with logical flow from overview to templates to patterns
Clear decision trees and matrices help users choose the right component type
Templates are complete with all required frontmatter fields documented
Excellent use of tables for quick reference
Good balance between comprehensive and concise
Anti-patterns section effectively shows what to avoid with concrete examples

Potential Bugs

No issues found
Referenced documentation files exist (verified: writing-skills.md, writing-commands.md, writing-agents.md)
All file path patterns are consistent with existing codebase structure
Frontmatter fields match current SDK capabilities

Security Concerns

No security concerns identified
Content is purely educational/guidance
No executable code or commands that could cause harm

Style Notes

Consistent markdown formatting throughout
Frontmatter follows established conventions (name, description, user-invocable: false)
Examples use realistic component names from the actual codebase
Naming conventions align with existing patterns (kebab-case for files/folders, UPPERCASE for SKILL.md/AGENT.md)

Test Coverage

Not applicable for documentation/skill content
Consider testing auto-activation by verifying the description triggers appropriately when users discuss creating new capabilities

Additional Observations

The 20% skill auto-activation stat (line 260) is a valuable insight that justifies the @ reference pattern
Model selection guidance is practical and reflects real-world usage patterns
Checklists at the end provide actionable quality gates
The decision tree (lines 27-41) is particularly helpful for newcomers

Verdict

LGTM

This is a high-quality skill that fills an important gap in the architecture repository. It codifies best practices for capability design and will improve consistency across new components. The templates, decision trees, and anti-patterns make this immediately actionable. Ready to merge.

## AI Code Review > This is an automated review generated by the code-reviewer agent. ### Summary Excellent addition to the architecture repository. This skill provides comprehensive, well-structured guidance for creating capabilities (skills, commands, and agents). The content is clear, practical, and follows established patterns in the codebase. ### Findings #### Code Quality - Well-organized structure with logical flow from overview to templates to patterns - Clear decision trees and matrices help users choose the right component type - Templates are complete with all required frontmatter fields documented - Excellent use of tables for quick reference - Good balance between comprehensive and concise - Anti-patterns section effectively shows what to avoid with concrete examples #### Potential Bugs - No issues found - Referenced documentation files exist (verified: writing-skills.md, writing-commands.md, writing-agents.md) - All file path patterns are consistent with existing codebase structure - Frontmatter fields match current SDK capabilities #### Security Concerns - No security concerns identified - Content is purely educational/guidance - No executable code or commands that could cause harm #### Style Notes - Consistent markdown formatting throughout - Frontmatter follows established conventions (name, description, user-invocable: false) - Examples use realistic component names from the actual codebase - Naming conventions align with existing patterns (kebab-case for files/folders, UPPERCASE for SKILL.md/AGENT.md) #### Test Coverage - Not applicable for documentation/skill content - Consider testing auto-activation by verifying the description triggers appropriately when users discuss creating new capabilities #### Additional Observations - The 20% skill auto-activation stat (line 260) is a valuable insight that justifies the @ reference pattern - Model selection guidance is practical and reflects real-world usage patterns - Checklists at the end provide actionable quality gates - The decision tree (lines 27-41) is particularly helpful for newcomers ### Verdict **LGTM** This is a high-quality skill that fills an important gap in the architecture repository. It codifies best practices for capability design and will improve consistency across new components. The templates, decision trees, and anti-patterns make this immediately actionable. Ready to merge.

HugoNijhuis merged commit c9a72bf1d3 into main

2026-01-10 14:44:26 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: flowmade-one/architecture#77