3.7 KiB
name, description
| name | description |
|---|---|
| capability-authoring | Guide for creating and evolving learned capabilities |
Capability Authoring
When your owner wants you to learn a new ability, you create a capability together. This guide tells you how to write, format, and register it.
Capability Types
A capability can take several forms:
Prompt (default)
A markdown file with guidance on what to achieve. Best for judgment-based tasks where you need flexibility — brainstorming, analysis, coaching, review.
capabilities/
└── blog-ideation.md
Script
A Python or bash script for deterministic tasks — calculations, file processing, data transformation, API calls. Create the script alongside a short markdown file that describes when and how to use it.
capabilities/
├── weekly-stats.md # When to run, what to do with results
└── weekly-stats.py # The actual computation
Multi-file
A folder with multiple files for complex capabilities — mini-workflows with multiple steps, reference materials, templates.
capabilities/
└── pitch-builder/
├── pitch-builder.md # Main guidance
├── structure.md # Pitch structure reference
└── examples.md # Example pitches for tone
External Skill Reference
Point to an existing installed skill rather than reinventing it. If you discover a skill that would serve your owner well, suggest it — but always ask before installing.
## Learned
| Code | Name | Description | Source | Added |
|------|------|-------------|--------|-------|
| [PR] | Create PRD | Product requirements | External: `bmad-create-prd` | 2026-03-25 |
Prompt File Format
Every capability prompt file should have this frontmatter:
---
name: {kebab-case-name}
description: {one line — what this does}
code: {2-letter menu code, unique across all capabilities}
added: {YYYY-MM-DD}
type: prompt | script | multi-file | external
---
The body should be outcome-focused — describe what success looks like, not step-by-step instructions. Include:
- What Success Looks Like — the outcome, not the process
- Context — constraints, preferences, domain knowledge
- Memory Integration — how to use MEMORY.md and BOND.md to personalize
- After Use — what to capture in the session log
Creating a Capability (The Flow)
- Owner says they want you to do something new
- Explore what they need through conversation — don't rush to write
- Draft the capability prompt and show it to them
- Refine based on feedback
- Save to
capabilities/(file or folder depending on type) - Update CAPABILITIES.md — add a row to the Learned table
- Update INDEX.md — note the new file under "My Files"
- Confirm: "I'll remember how to do this next session. You can trigger it with [{code}]."
Scripts
When a capability needs deterministic logic (math, file parsing, API calls), write a script:
- Python preferred for portability
- Keep scripts focused — one job per script
- The companion markdown file says WHEN to run the script and WHAT to do with results
- Scripts should read from and write to files in the sanctum
- Never hardcode paths — accept sanctum path as argument
Refining Capabilities
Capabilities evolve. After use, if the owner gives feedback:
- Update the capability prompt with refined context
- Add to the "Owner Preferences" section if one exists
- Log the refinement in the session log
A capability that's been refined 3-4 times is usually excellent. The first draft is rarely the best.
Retiring Capabilities
If a capability is no longer useful:
- Remove its row from CAPABILITIES.md
- Keep the file (don't delete — the owner might want it back)
- Note the retirement in the session log