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