Skip to content
This repository was archived by the owner on Apr 11, 2026. It is now read-only.

Commit d997c7b

Browse files
committed
skills: update skill-create to enforce skill-anatomy.md template
1 parent d5c1549 commit d997c7b

1 file changed

Lines changed: 28 additions & 7 deletions

File tree

skills/flow-code-skill-create/SKILL.md

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: Use when creating new flow-code skills, editing existing skills, or
55

66
# Creating Flow-Code Skills
77

8+
**Template spec:** See [docs/skill-anatomy.md](../../docs/skill-anatomy.md) for the full specification.
9+
810
Writing skills IS Test-Driven Development applied to documentation. If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
911

1012
## When to Create
@@ -46,12 +48,27 @@ Core principle in 1-2 sentences.
4648

4749
## When to Use
4850
Symptoms, triggers, use cases.
51+
- **When NOT to use:** exclusions to prevent misapplication
4952

5053
## Core Process / Pattern
5154
The actual workflow — inline code for simple patterns.
5255

53-
## Common Mistakes
54-
What goes wrong + fixes.
56+
## Common Rationalizations
57+
58+
| Excuse | Reality |
59+
|--------|---------|
60+
| "Too simple to need this" | Simple things break too |
61+
| "I'll do it properly later" | Later never comes |
62+
| "I already know this" | Knowing != doing consistently |
63+
64+
## Red Flags
65+
- Observable symptoms indicating the skill is being violated
66+
- Patterns to watch for during self-check and review
67+
68+
## Verification
69+
After completing the process, confirm:
70+
- [ ] Checklist item with verifiable evidence
71+
- [ ] Another checkpoint (test output, build result, etc.)
5572
```
5673

5774
## The Iron Law
@@ -92,9 +109,9 @@ NO SKILL WITHOUT A FAILING TEST FIRST
92109
- Exclude: workflow summary, process steps, what the skill does
93110
- Keywords in body for discovery: error messages, symptoms, tool names
94111

95-
## Bulletproofing Discipline Skills
112+
## Bulletproofing All Skills
96113

97-
For skills that enforce rules (debugging, TDD, verification):
114+
Every skill — not just discipline skills — needs rationalization counters and red flags. Agents rationalize skipping steps in ALL skill types (technique, pattern, and reference). The sections below apply universally.
98115

99116
**Close every loophole explicitly:**
100117
```markdown
@@ -133,14 +150,18 @@ Write code before test? Delete it. Start over.
133150
- [ ] Failure patterns identified
134151

135152
**GREEN:**
136-
- [ ] SKILL.md with frontmatter, overview, process, mistakes
153+
- [ ] SKILL.md with frontmatter, overview, process
137154
- [ ] Description starts with "Use when..." (no workflow summary)
138155
- [ ] Scenario re-run with skill — agent complies
156+
- [ ] "When NOT to use" included in When to Use section
157+
- [ ] Common Rationalizations table present (>=3 entries)
158+
- [ ] Red Flags list present (observable symptoms, not opinions)
159+
- [ ] Verification checklist present (checkbox format)
139160

140161
**REFACTOR:**
141162
- [ ] New rationalizations countered
142-
- [ ] Rationalization table added (if discipline skill)
143-
- [ ] Red flags list added (if discipline skill)
163+
- [ ] Rationalization table complete (covers all observed agent excuses)
164+
- [ ] Red flags list complete (covers all observed violation patterns)
144165

145166
**DEPLOY:**
146167
- [ ] Committed to git

0 commit comments

Comments
 (0)