Skill Name
Brief introduction to what this skill provides (1-2 sentences maximum).
NEVER Do [Domain-Specific Anti-Patterns]
- NEVER [specific anti-pattern 1] - [Why this fails / non-obvious consequence]. [Example if helpful].
- NEVER [specific anti-pattern 2] - [Concrete reason from experience].
- NEVER [specific anti-pattern 3] - [What happens when violated].
- NEVER [generic mistake in this domain] - [Why experts avoid this].
- NEVER [common beginner error] - [Non-obvious reason it's problematic].
Before [Domain Action], Ask
Apply these tests before [performing key domain action]:
[Expert Thinking Framework 1]
- [Key Question]? [Guidance on what to consider]. [Consequence if ignored].
- [Key Question]? [How experts think about this]. [Example if needed].
[Expert Thinking Framework 2]
- [Key Question]? [Critical consideration]. [Trade-off to understand].
- [Key Question]? [Decision criteria]. [What to optimize for].
[Expert Thinking Framework 3]
- [Key Question]? [Edge case consideration]. [When standard approach fails].
How to Use
This skill uses progressive disclosure to minimize context usage:
1. Start with the Workflow (SKILL.md)
Follow the [workflow/decision tree/process] below for [domain task].
2. Reference Implementation Details (AGENTS.md)
Load AGENTS.md for [specific type of guidance: file conventions / optimization rules / architectural patterns].
3. Load Specific Examples as Needed
When [specific scenario], load corresponding reference files for ❌/✅ examples:
- [Scenario 1] → Load reference-file-1.md
- [Scenario 2] → Load reference-file-2.md
[Main Workflow / Decision Tree / Process]
[Your workflow/decision tree/creative guidance here]
Freedom Calibration
Calibrate guidance specificity to task fragility:
| Task Type |
Freedom Level |
Guidance Format |
Example |
| Creative/Design |
High freedom |
Principles, thinking patterns, anti-patterns |
"[Creative principle]" |
| Analysis/Review |
Medium freedom |
Guidelines with examples, decision frameworks |
"Priority: [ordered list]" |
| File Operations |
Low freedom |
Exact scripts, specific steps, no variation |
"Use exact command: [cmd]" |
The test: "If the agent makes a mistake, what's the consequence?"
- High consequence (corruption, data loss) → Low freedom with precise scripts
- Medium consequence (suboptimal result, style issues) → Medium freedom with examples
- Low consequence (aesthetic choices, multiple valid approaches) → High freedom with principles
Important Notes
- [Critical non-obvious consideration that affects success]
- [Edge case that's easy to miss]
- [Domain-specific constraint or requirement]
1---2name: skill-name3description: Use when users say "[trigger phrase 1]", "[trigger phrase 2]", or when [specific scenario]. [WHAT this skill does]. [Additional trigger keywords for searchability].4license: Apache-2.05---6
7# Skill Name
8
9Brief introduction to what this skill provides (1-2 sentences maximum).
10
11## NEVER Do [Domain-Specific Anti-Patterns]
12
13<!-- CRITICAL: This section is half of expert knowledge.
14 Good anti-patterns are SPECIFIC with WHY (non-obvious reasons).
15 Bad anti-patterns are vague warnings like "be careful" or "avoid errors".
16
17 Ask yourself: "Would an expert say 'yes, I learned this the hard way'?"
18
19 Include 5-8 specific anti-patterns with concrete reasons.
20-->
21
22- **NEVER [specific anti-pattern 1]** - [Why this fails / non-obvious consequence]. [Example if helpful].
23- **NEVER [specific anti-pattern 2]** - [Concrete reason from experience].
24- **NEVER [specific anti-pattern 3]** - [What happens when violated].
25- **NEVER [generic mistake in this domain]** - [Why experts avoid this].
26- **NEVER [common beginner error]** - [Non-obvious reason it's problematic].
27
28<!-- Examples from real skills:
29 - NEVER write tutorials explaining basics - Claude knows standard concepts. Focus on expert-only knowledge.
30 - NEVER use Inter/Roboto fonts - Overused in AI-generated designs, lacks originality.
31 - NEVER edit OOXML directly without unpacking first - XML structure breaks, file corrupts.
32-->
33
34## Before [Domain Action], Ask
35
36<!-- CRITICAL: Teach THINKING PATTERNS, not just procedures.
37 This transforms agents from "following steps" to "making expert decisions".
38
39 Format: "Before [action], ask yourself:"
40 Include 3-5 key questions experts ask before acting.
41 These should shape HOW agents think about the problem.
42-->
43
44Apply these tests before [performing key domain action]:
45
46### [Expert Thinking Framework 1]
47- **[Key Question]?** [Guidance on what to consider]. [Consequence if ignored].
48- **[Key Question]?** [How experts think about this]. [Example if needed].
49
50### [Expert Thinking Framework 2]
51- **[Key Question]?** [Critical consideration]. [Trade-off to understand].
52- **[Key Question]?** [Decision criteria]. [What to optimize for].
53
54### [Expert Thinking Framework 3]
55- **[Key Question]?** [Edge case consideration]. [When standard approach fails].
56
57<!-- Examples from real skills:
58 "Before Creating a Skill, Ask:"
59 - Does this capture what takes experts years to learn?
60 - Am I explaining TO Claude or arming Claude?
61
62 "Before Designing, Ask:"
63 - What makes this memorable vs generic?
64 - What extreme aesthetic direction fits the purpose?
65-->
66
67## How to Use
68
69<!-- Choose ONE structure based on skill complexity:
70
71 OPTION A - For SIMPLE skills (<100 lines, single workflow, no references):
72 Delete this section and put direct instructions here. Example:
73 "Run `scripts/process.sh <input>` to process files. See examples in `assets/`."
74
75 OPTION B - For COMPLEX skills (rules, references, multiple scenarios):
76 Use progressive disclosure pattern below.
77
78 NEVER mix both - either direct instructions OR progressive disclosure.
79-->
80
81This skill uses **progressive disclosure** to minimize context usage:
82
83### 1. Start with the Workflow (SKILL.md)
84Follow the [workflow/decision tree/process] below for [domain task].
85
86### 2. Reference Implementation Details (AGENTS.md)
87Load [AGENTS.md](AGENTS.md) for [specific type of guidance: file conventions / optimization rules / architectural patterns].
88
89### 3. Load Specific Examples as Needed
90When [specific scenario], load corresponding reference files for ❌/✅ examples:
91- [Scenario 1] → Load [reference-file-1.md](references/reference-file-1.md)
92- [Scenario 2] → Load [reference-file-2.md](references/reference-file-2.md)
93
94## [Main Workflow / Decision Tree / Process]
95
96<!-- This is the CORE of your skill. Choose format based on task type:
97
98 For PHASED WORKFLOWS (Process pattern ~200 lines):
99 - Step-by-step numbered workflow
100 - Include checklist for tracking progress
101 - "Skip this step only when..." guidance
102
103 For DECISION TREES (Tool pattern ~300 lines):
104 - Table format: "Scenario | Approach | Fallback"
105 - If/then logic with clear branches
106 - Error handling and edge cases
107
108 For CREATIVE GUIDANCE (Mindset pattern ~50 lines):
109 - Principles over procedures
110 - High freedom with examples
111 - Focus on taste and judgment
112
113 Include DOMAIN-SPECIFIC procedures Claude wouldn't know.
114 NEVER include generic procedures (open file, edit, save).
115-->
116
117[Your workflow/decision tree/creative guidance here]
118
119## Freedom Calibration
120
121<!-- ONLY include this section if your skill needs to teach agents how to calibrate freedom.
122 Most skills don't need this - it's for meta-skills or skills that work across task types.
123
124 If your skill is ONLY creative → Don't include (just use high freedom throughout)
125 If your skill is ONLY fragile ops → Don't include (just use low freedom throughout)
126 If your skill spans multiple task types → Include this table
127-->
128
129**Calibrate guidance specificity to task fragility:**
130
131| Task Type | Freedom Level | Guidance Format | Example |
132|-----------|---------------|-----------------|---------|
133| **Creative/Design** | High freedom | Principles, thinking patterns, anti-patterns | "[Creative principle]" |
134| **Analysis/Review** | Medium freedom | Guidelines with examples, decision frameworks | "Priority: [ordered list]" |
135| **File Operations** | Low freedom | Exact scripts, specific steps, no variation | "Use exact command: `[cmd]`" |
136
137**The test:** "If the agent makes a mistake, what's the consequence?"
138- High consequence (corruption, data loss) → Low freedom with precise scripts
139- Medium consequence (suboptimal result, style issues) → Medium freedom with examples
140- Low consequence (aesthetic choices, multiple valid approaches) → High freedom with principles
141
142## Important Notes
143
144<!-- Only include NON-OBVIOUS critical considerations.
145 NEVER include obvious reminders like "test your code" or "handle errors".
146 Think: "What do experts know that isn't written elsewhere?"
147-->
148
149- [Critical non-obvious consideration that affects success]
150- [Edge case that's easy to miss]
151- [Domain-specific constraint or requirement]
152
153<!-- DELETE "Additional Resources" section - it's redundant with "How to Use" section.
154 Progressive disclosure is already explained above.
155-->
gohypergiant