nangohq
Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples
bunx add-skill nangohq/nango -s creating-skillsLoadingβ¦
Skills are reference guides for proven techniques, patterns, or tools. Write them to help future Claude instances quickly find and apply effective approaches.
Skills must be discoverable (Claude can find them), scannable (quick to evaluate), and actionable (clear examples).
Core principle: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
Create a skill when:
Don't create for:
.claude/CLAUDE.md)---
name: skill-name-with-hyphens
description: Use when [triggers/symptoms] - [what it does and how it helps]
tags: relevant-tags
---
Rules:
name and fields supported (max 1024 chars total)description# Skill Name
## Overview
Core principle in 1-2 sentences. What is this?
## When to Use
- Bullet list with symptoms and use cases
- When NOT to use
## Quick Reference
Table or bullets for common operations
## Implementation
Inline code for simple patterns
Link to separate file for heavy reference (100+ lines)
## Common Mistakes
What goes wrong + how to fix
## Real-World Impact (optional)
Concrete results from using this technique
Match specificity to task complexity:
High freedom: Flexible tasks requiring judgment
Low freedom: Fragile or critical operations
Red flag: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.
Critical: Future Claude reads the description to decide if skill is relevant. Optimize for discovery.
# β BAD - Too vague, doesn't mention when to use
description: For async testing
# β BAD - First person (injected into system prompt)
description: I help you with flaky tests
# β
GOOD - Triggers + what it does
description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
# β
GOOD - Technology-specific with explicit trigger
description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management
Use words Claude would search for:
Use gerund form (verb + -ing):
creating-skills not skill-creationtesting-with-subagents not subagent-testingdebugging-memory-leaks not memory-leak-debuggingprocessing-pdfs not pdf-processoranalyzing-spreadsheets not spreadsheet-analysisWhy gerunds work:
Avoid:
One excellent example beats many mediocre ones.
// β
GOOD - Clear, complete, ready to adapt
interface RetryOptions {
maxAttempts: number;
delayMs: number;
backoff?: 'linear' | 'exponential';
}
async function retryOperation<T>(
operation: () => Promise<T>,
options: RetryOptions
): Promise<T> {
const { maxAttempts, delayMs, backoff = 'linear' } = options;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await operation();
} catch (error) {
if (attempt === maxAttempts) throw error;
const delay = backoff === 'exponential'
? delayMs * Math.pow(2, attempt - 1)
: delayMs * attempt;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('Unreachable');
}
// Usage
const data = await retryOperation(
() => fetchUserData(userId),
{ maxAttempts: 3, delayMs: 1000, backoff: 'exponential' }
);
typescript-type-safety/
SKILL.md # Everything inline
When: All content fits in ~500 words, no heavy reference needed
api-integration/
SKILL.md # Overview + patterns
retry-helpers.ts # Reusable code
examples/
auth-example.ts
pagination-example.ts
When: Reusable tools or multiple complete examples needed
aws-sdk/
SKILL.md # Overview + workflows
s3-api.md # 600 lines API reference
lambda-api.md # 500 lines API reference
When: Reference material > 100 lines
Skills load into every conversation. Keep them concise.
Challenge each piece of information: "Does Claude really need this explanation?"
# β BAD - Verbose (42 words)
Your human partner asks: "How did we handle authentication errors in React Router before?"
You should respond: "I'll search past conversations for React Router authentication patterns."
Then dispatch a subagent with the search query: "React Router authentication error handling 401"
# β
GOOD - Concise (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent β synthesis]
Techniques:
--help instead of documenting all flagsFor multi-step processes, include:
Example structure:
## Workflow
1. **Preparation**
- Check prerequisites
- Validate environment
2. **Execution**
- Step 1: [action + expected result]
- Step 2: [action + expected result]
3. **Verification**
- [ ] Check 1 passes
- [ ] Check 2 passes
4. **Rollback** (if needed)
- Steps to undo changes
| Mistake | Why It Fails | Fix |
|---|---|---|
| Narrative example | "In session 2025-10-03..." | Focus on reusable pattern |
| Multi-language dilution | Same example in 5 languages | One excellent example |
| Code in flowcharts | step1 [label="import fs"] | Use markdown code blocks |
| Generic labels | helper1, helper2, step3 | Use semantic names |
| Missing description triggers | "For testing" | "Use when tests are flaky..." |
| First-person description | "I help you..." | "Use when... - provides..." |
| Deeply nested file references | Multiple @ symbols, complex paths | Keep references simple and direct |
| Windows-style file paths | C:\path\to\file | Use forward slashes |
| Offering too many options | 10 different approaches | Focus on one proven approach |
| Punting error handling | "Claude figures it out" | Include explicit error handling in scripts |
| Time-sensitive information | "As of 2025..." | Keep content evergreen |
| Inconsistent terminology | Mixing synonyms randomly | Use consistent terms throughout |
Only use flowcharts for:
Never use for:
# β
GOOD - Name only with clear requirement
**REQUIRED:** Use superpowers:test-driven-development before proceeding
**RECOMMENDED:** See typescript-type-safety for proper type guards
# β BAD - Unclear if required
See skills/testing/test-driven-development
# β BAD - Force-loads file, wastes context
@skills/testing/test-driven-development/SKILL.md
Best approach: Develop skills iteratively with Claude
Before extensive documentation:
For reliability, provide:
Example:
#!/bin/bash
set -e # Exit on error
if [ ! -f "config.json" ]; then
echo "Error: config.json not found" >&2
exit 1
fi
# Script logic here
echo "Success"
exit 0
When skills produce consistent formats:
## Output Template
\`\`\`typescript
interface ExpectedOutput {
status: 'success' | 'error';
data: YourDataType;
errors?: string[];
}
\`\`\`
**Usage**: Copy and adapt for your context
Before writing:
Frontmatter:
Content:
Quality:
Testing (if discipline-enforcing skill):
skills/
skill-name/
SKILL.md # Required
supporting-file.* # Optional
examples/ # Optional
example1.ts
scripts/ # Optional
helper.py
Flat namespace - all skills in one searchable directory
Good skills:
Bad skills:
Remember: Skills are for future Claude, not current you. Optimize for discovery, scanning, and action.
Golden rule: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
Use when you need to run Flow type checking, or when seeing Flow type errors in React code.
Use when you want to validate changes before committing, or when you need to check all React contribution requirements.
Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.
Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels.