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

Create capability-writing skill with templates and design guidance #74

New Issue
Closed
opened 2026-01-10 14:27:10 +00:00 by HugoNijhuis · 0 comments
HugoNijhuis commented 2026-01-10 14:27:10 +00:00
Owner
Copy Link

Summary

Create a skill that teaches Claude how to design and create capabilities for this repository. A capability is often a cohesive set of components (skill + command + agent) that work together.

For

Flowmade Developers - "Help me encode best practices so AI applies them"

What This Skill Should Include

Component Templates

Skill template (skills/name/SKILL.md):

---
name: skill-name
description: >
  What this skill teaches and when to use it.
  Include trigger conditions in description (not body).
user-invocable: false
---

Command template (commands/name.md):

---
description: What this command does
argument-hint: <required> [optional]
model: sonnet  # or haiku for lightweight commands
allowed-tools: Tool1, Tool2  # optional restriction
---

Agent template (agents/name/AGENT.md):

---
name: agent-name
description: What this agent does and when to spawn it
model: sonnet  # or opus for complex reasoning
skills: skill1, skill2
tools: Bash, Read, Write, Edit, Glob, Grep
disallowedTools:  # optional - e.g., Edit, Write for read-only agents
---

Capability Design Guidance

When do you need each component?

Need Component Example
Knowledge Claude should apply automatically Skill software-architecture
User-invoked workflow Command /work-issue
Isolated subtask with focused context Agent code-reviewer
All three Full capability arch-review (skill + command + agent)

Decision tree:

  • Just knowledge? → Skill only
  • User workflow using existing knowledge? → Command + reference skills
  • Complex isolated work? → Command + Agent (agent uses skills)
  • New domain expertise + workflow + isolated work? → All three

Model Selection Guidance

Model Use When Examples
haiku Simple fetch/display, formatting, mechanical tasks /dashboard, /roadmap
sonnet Most commands and agents, balanced performance /work-issue, issue-worker
opus Deep reasoning, architectural analysis, complex judgment software-architect

Conventions

  • Skills: skills/name/SKILL.md (uppercase)
  • Commands: commands/name.md (lowercase)
  • Agents: agents/name/AGENT.md (uppercase) - see issue #68
  • Reference skills: @~/.claude/skills/name/SKILL.md
  • Agent skill list: skills: skill1, skill2 (names only, no paths)

Acceptance Criteria

  • Skill created at skills/capability-writing/SKILL.md
  • Includes templates for all three component types
  • Includes capability design guidance (when to use what)
  • Includes model selection guidance
  • Includes conventions and anti-patterns
  • References existing docs in docs/ directory

Context

Supports /create-capability command. Part of meta-tooling for extending the architecture repo.

## Summary Create a skill that teaches Claude how to design and create capabilities for this repository. A capability is often a cohesive set of components (skill + command + agent) that work together. ## For Flowmade Developers - "Help me encode best practices so AI applies them" ## What This Skill Should Include ### Component Templates **Skill template** (`skills/name/SKILL.md`): ```yaml --- name: skill-name description: > What this skill teaches and when to use it. Include trigger conditions in description (not body). user-invocable: false --- ``` **Command template** (`commands/name.md`): ```yaml --- description: What this command does argument-hint: <required> [optional] model: sonnet # or haiku for lightweight commands allowed-tools: Tool1, Tool2 # optional restriction --- ``` **Agent template** (`agents/name/AGENT.md`): ```yaml --- name: agent-name description: What this agent does and when to spawn it model: sonnet # or opus for complex reasoning skills: skill1, skill2 tools: Bash, Read, Write, Edit, Glob, Grep disallowedTools: # optional - e.g., Edit, Write for read-only agents --- ``` ### Capability Design Guidance When do you need each component? | Need | Component | Example | |------|-----------|---------| | Knowledge Claude should apply automatically | Skill | `software-architecture` | | User-invoked workflow | Command | `/work-issue` | | Isolated subtask with focused context | Agent | `code-reviewer` | | All three | Full capability | arch-review (skill + command + agent) | Decision tree: - Just knowledge? → Skill only - User workflow using existing knowledge? → Command + reference skills - Complex isolated work? → Command + Agent (agent uses skills) - New domain expertise + workflow + isolated work? → All three ### Model Selection Guidance | Model | Use When | Examples | |-------|----------|----------| | `haiku` | Simple fetch/display, formatting, mechanical tasks | `/dashboard`, `/roadmap` | | `sonnet` | Most commands and agents, balanced performance | `/work-issue`, `issue-worker` | | `opus` | Deep reasoning, architectural analysis, complex judgment | `software-architect` | ### Conventions - Skills: `skills/name/SKILL.md` (uppercase) - Commands: `commands/name.md` (lowercase) - Agents: `agents/name/AGENT.md` (uppercase) - see issue #68 - Reference skills: `@~/.claude/skills/name/SKILL.md` - Agent skill list: `skills: skill1, skill2` (names only, no paths) ## Acceptance Criteria - [ ] Skill created at `skills/capability-writing/SKILL.md` - [ ] Includes templates for all three component types - [ ] Includes capability design guidance (when to use what) - [ ] Includes model selection guidance - [ ] Includes conventions and anti-patterns - [ ] References existing docs in `docs/` directory ## Context Supports `/create-capability` command. Part of meta-tooling for extending the architecture repo.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
HugoNijhuis fluxcd-bot renovate-bot
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#75 Create /create-capability command for scaffolding capability sets
flowmade-one/architecture
Reference: flowmade-one/architecture#74
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?