1# Skill Template
2 
3Template for creating skills extracted from learnings. Copy and customize.
4 
5---
6 
7## SKILL.md Template
8 
9```markdown
10---
11name: skill-name-here
12description: "Concise description of when and why to use this skill. Include trigger conditions."
13---
14 
15# Skill Name
16 
17Brief introduction explaining the problem this skill solves and its origin.
18 
19## Quick Reference
20 
21| Situation | Action |
22|-----------|--------|
23| [Trigger 1] | [Action 1] |
24| [Trigger 2] | [Action 2] |
25 
26## Background
27 
28Why this knowledge matters. What problems it prevents. Context from the original learning.
29 
30## Solution
31 
32### Step-by-Step
33 
341. First step with code or command
352. Second step
363. Verification step
37 
38### Code Example
39 
40\`\`\`language
41// Example code demonstrating the solution
42\`\`\`
43 
44## Common Variations
45 
46- **Variation A**: Description and how to handle
47- **Variation B**: Description and how to handle
48 
49## Gotchas
50 
51- Warning or common mistake #1
52- Warning or common mistake #2
53 
54## Related
55 
56- Link to related documentation
57- Link to related skill
58 
59## Source
60 
61Extracted from learning entry.
62- **Learning ID**: LRN-YYYYMMDD-XXX
63- **Original Category**: correction | insight | knowledge_gap | best_practice
64- **Extraction Date**: YYYY-MM-DD
65```
66 
67---
68 
69## Minimal Template
70 
71For simple skills that don't need all sections:
72 
73```markdown
74---
75name: skill-name-here
76description: "What this skill does and when to use it."
77---
78 
79# Skill Name
80 
81[Problem statement in one sentence]
82 
83## Solution
84 
85[Direct solution with code/commands]
86 
87## Source
88 
89- Learning ID: LRN-YYYYMMDD-XXX
90```
91 
92---
93 
94## Template with Scripts
95 
96For skills that include executable helpers:
97 
98```markdown
99---
100name: skill-name-here
101description: "What this skill does and when to use it."
102---
103 
104# Skill Name
105 
106[Introduction]
107 
108## Quick Reference
109 
110| Command | Purpose |
111|---------|---------|
112| `./scripts/helper.sh` | [What it does] |
113| `./scripts/validate.sh` | [What it does] |
114 
115## Usage
116 
117### Automated (Recommended)
118 
119\`\`\`bash
120./skills/skill-name/scripts/helper.sh [args]
121\`\`\`
122 
123### Manual Steps
124 
1251. Step one
1262. Step two
127 
128## Scripts
129 
130| Script | Description |
131|--------|-------------|
132| `scripts/helper.sh` | Main utility |
133| `scripts/validate.sh` | Validation checker |
134 
135## Source
136 
137- Learning ID: LRN-YYYYMMDD-XXX
138```
139 
140---
141 
142## Naming Conventions
143 
144- **Skill name**: lowercase, hyphens for spaces
145  - Good: `docker-m1-fixes`, `api-timeout-patterns`
146  - Bad: `Docker_M1_Fixes`, `APITimeoutPatterns`
147 
148- **Description**: Start with action verb, mention trigger
149  - Good: "Handles Docker build failures on Apple Silicon. Use when builds fail with platform mismatch."
150  - Bad: "Docker stuff"
151 
152- **Files**:
153  - `SKILL.md` - Required, main documentation
154  - `scripts/` - Optional, executable code
155  - `references/` - Optional, detailed docs
156  - `assets/` - Optional, templates
157 
158---
159 
160## Extraction Checklist
161 
162Before creating a skill from a learning:
163 
164- [ ] Learning is verified (status: resolved)
165- [ ] Solution is broadly applicable (not one-off)
166- [ ] Content is complete (has all needed context)
167- [ ] Name follows conventions
168- [ ] Description is concise but informative
169- [ ] Quick Reference table is actionable
170- [ ] Code examples are tested
171- [ ] Source learning ID is recorded
172 
173After creating:
174 
175- [ ] Update original learning with `promoted_to_skill` status
176- [ ] Add `Skill-Path: skills/skill-name` to learning metadata
177- [ ] Test skill by reading it in a fresh session
178