You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 11, 2026. It is now read-only.
Copy file name to clipboardExpand all lines: skills/flow-code-skill-create/SKILL.md
+28-7Lines changed: 28 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,8 @@ description: Use when creating new flow-code skills, editing existing skills, or
5
5
6
6
# Creating Flow-Code Skills
7
7
8
+
**Template spec:** See [docs/skill-anatomy.md](../../docs/skill-anatomy.md) for the full specification.
9
+
8
10
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.
9
11
10
12
## When to Create
@@ -46,12 +48,27 @@ Core principle in 1-2 sentences.
46
48
47
49
## When to Use
48
50
Symptoms, triggers, use cases.
51
+
-**When NOT to use:** exclusions to prevent misapplication
49
52
50
53
## Core Process / Pattern
51
54
The actual workflow — inline code for simple patterns.
52
55
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 |
- 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.)
55
72
```
56
73
57
74
## The Iron Law
@@ -92,9 +109,9 @@ NO SKILL WITHOUT A FAILING TEST FIRST
92
109
- Exclude: workflow summary, process steps, what the skill does
93
110
- Keywords in body for discovery: error messages, symptoms, tool names
94
111
95
-
## Bulletproofing Discipline Skills
112
+
## Bulletproofing All Skills
96
113
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.
98
115
99
116
**Close every loophole explicitly:**
100
117
```markdown
@@ -133,14 +150,18 @@ Write code before test? Delete it. Start over.
133
150
-[ ] Failure patterns identified
134
151
135
152
**GREEN:**
136
-
-[ ] SKILL.md with frontmatter, overview, process, mistakes
153
+
-[ ] SKILL.md with frontmatter, overview, process
137
154
-[ ] Description starts with "Use when..." (no workflow summary)
138
155
-[ ] 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)
0 commit comments