Create
Purpose
Create new skills and agents for the ai-engineering framework using TDD. Skills go through a pressure-test cycle (RED/GREEN/REFACTOR) to ensure they actually change agent behavior. Agents are scaffolded with mandate, self-challenge protocol, and capability declarations.
Trigger
- Command:
/ai-create skill <name> or /ai-create agent <name>
- Context: framework needs a new capability that no existing skill or agent covers.
Modes
skill -- Create a new skill
Phase RED -- Baseline without the skill:
- Define test scenarios -- write 3-5 prompts that the skill should handle. These are the "pressure tests."
- Run baseline -- execute the prompts WITHOUT the new skill loaded. Record how the agent behaves.
- Identify gaps -- document specific failures: wrong approach, missed steps, bad output format, skipped governance.
Phase GREEN -- Write minimal skill:
- Scaffold -- create
.claude/skills/ai-{name}/SKILL.md with frontmatter:---
name: ai-{name}
description: "{CSO-optimized: Use when [triggering conditions]}"
argument-hint: "{expected arguments}"
---
- Write skill body -- address ONLY the gaps found in RED phase. Include:
- Purpose (2-3 lines)
- Trigger (command + context)
- Procedure (numbered steps)
- When NOT to Use (differentiation from similar skills)
- CSO-optimize description -- the
description field is the skill's search ranking. It must describe triggering conditions, not summarize what the skill does. Pattern: "Use when [specific situation the user is in]".
- Run pressure tests again -- verify the skill changes behavior for all test scenarios.
Phase REFACTOR -- Close loopholes:
- Test edge cases -- try prompts that should NOT trigger this skill. Verify they do not.
- Add guardrails -- if edge-case prompts incorrectly triggered the skill, add "When NOT to Use" entries.
- Final validation -- all pressure tests pass, no false triggers.
agent -- Create a new agent
- Define mandate -- what is this agent's singular responsibility? An agent does ONE thing.
- Scaffold -- create
.claude/agents/ai-{name}.md with:
- Identity (role, experience level, specialization)
- Mandate (what it owns, what it does not own)
- Capabilities (declared permissions: read-only, read-write, which files/paths)
- Behavior (modes, procedures)
- Boundaries (hard limits, escalation protocol)
- Self-challenge protocol (questions the agent asks itself before acting)
- Register -- add to
manifest.yml agents section.
- Create skill entry point -- create matching
/ai-{name} skill that activates the agent.
Registration Checklist
After creating any skill or agent:
CSO Description Patterns
| Bad (summary) |
Good (CSO trigger) |
| "Generates standup notes" |
"Use when preparing daily standup notes or summarizing recent PR activity" |
| "Sprint planning tool" |
"Use when planning a new sprint or running a retrospective" |
| "Resolves git conflicts" |
"Use when git reports merge conflicts during rebase, merge, or cherry-pick" |
Quick Reference
/ai-create skill standup # create a new standup skill with TDD
/ai-create agent reviewer # create a new reviewer agent
Integration
- Calls:
handlers/create-skill.md, handlers/create-agent.md, handlers/validate.md
- Triggers sync:
python scripts/sync_command_mirrors.py after creation
$ARGUMENTS
1---2name: ai-create3description: Use when creating a new skill or agent for the ai-engineering framework, with TDD-based pressure testing and CSO-optimized descriptions.4---5
6
7# Create
8
9## Purpose
10
11Create new skills and agents for the ai-engineering framework using TDD. Skills go through a pressure-test cycle (RED/GREEN/REFACTOR) to ensure they actually change agent behavior. Agents are scaffolded with mandate, self-challenge protocol, and capability declarations.
12
13## Trigger
14
15- Command: `/ai-create skill <name>` or `/ai-create agent <name>`
16- Context: framework needs a new capability that no existing skill or agent covers.
17
18## Modes
19
20### skill <name> -- Create a new skill
21
22**Phase RED -- Baseline without the skill**:
23
241. **Define test scenarios** -- write 3-5 prompts that the skill should handle. These are the "pressure tests."
252. **Run baseline** -- execute the prompts WITHOUT the new skill loaded. Record how the agent behaves.
263. **Identify gaps** -- document specific failures: wrong approach, missed steps, bad output format, skipped governance.
27
28**Phase GREEN -- Write minimal skill**:
29
304. **Scaffold** -- create `.claude/skills/ai-{name}/SKILL.md` with frontmatter:
31 ```yaml
32 ---
33 name: ai-{name}
34 description: "{CSO-optimized: Use when [triggering conditions]}"
35 argument-hint: "{expected arguments}"
36 ---
37 ```
385. **Write skill body** -- address ONLY the gaps found in RED phase. Include:
39 - Purpose (2-3 lines)
40 - Trigger (command + context)
41 - Procedure (numbered steps)
42 - When NOT to Use (differentiation from similar skills)
436. **CSO-optimize description** -- the `description` field is the skill's search ranking. It must describe triggering conditions, not summarize what the skill does. Pattern: "Use when [specific situation the user is in]".
447. **Run pressure tests again** -- verify the skill changes behavior for all test scenarios.
45
46**Phase REFACTOR -- Close loopholes**:
47
488. **Test edge cases** -- try prompts that should NOT trigger this skill. Verify they do not.
499. **Add guardrails** -- if edge-case prompts incorrectly triggered the skill, add "When NOT to Use" entries.
5010. **Final validation** -- all pressure tests pass, no false triggers.
51
52### agent <name> -- Create a new agent
53
541. **Define mandate** -- what is this agent's singular responsibility? An agent does ONE thing.
552. **Scaffold** -- create `.claude/agents/ai-{name}.md` with:
56 - Identity (role, experience level, specialization)
57 - Mandate (what it owns, what it does not own)
58 - Capabilities (declared permissions: read-only, read-write, which files/paths)
59 - Behavior (modes, procedures)
60 - Boundaries (hard limits, escalation protocol)
61 - Self-challenge protocol (questions the agent asks itself before acting)
623. **Register** -- add to `manifest.yml` agents section.
634. **Create skill entry point** -- create matching `/ai-{name}` skill that activates the agent.
64
65## Registration Checklist
66
67After creating any skill or agent:
68
69- [ ] File created at correct path
70- [ ] Frontmatter has `name`, `description`, `argument-hint`
71- [ ] Description is CSO-optimized (triggering conditions, not summary)
72- [ ] Registered in `manifest.yml`
73- [ ] Mirror files created for other IDE surfaces (`.agents/`, `.github/prompts/`)
74- [ ] No overlap with existing skills (checked `/ai-find` or skill list)
75
76## CSO Description Patterns
77
78| Bad (summary) | Good (CSO trigger) |
79|---------------|-------------------|
80| "Generates standup notes" | "Use when preparing daily standup notes or summarizing recent PR activity" |
81| "Sprint planning tool" | "Use when planning a new sprint or running a retrospective" |
82| "Resolves git conflicts" | "Use when git reports merge conflicts during rebase, merge, or cherry-pick" |
83
84## Quick Reference
85
86```
87/ai-create skill standup # create a new standup skill with TDD
88/ai-create agent reviewer # create a new reviewer agent
89```
90
91## Integration
92
93- **Calls**: `handlers/create-skill.md`, `handlers/create-agent.md`, `handlers/validate.md`
94- **Triggers sync**: `python scripts/sync_command_mirrors.py` after creation
95
96$ARGUMENTS
majiayu000