From 64403a3686f964e50e2d0f7e40a7855516be44bc Mon Sep 17 00:00:00 2001 From: yusyus Date: Sun, 15 Mar 2026 02:51:02 +0300 Subject: [PATCH] docs: add best practices guide for high-quality skills (#206) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/BEST_PRACTICES.md — a comprehensive guide for creating high-quality Claude skills. Covers SKILL.md structure, code examples, prerequisites, troubleshooting, quality targets, and a real-world before/after example (Grade F to Grade A). Addresses roadmap item I2.2. Based on PR #206 by @jmagly from the AI Writing Guide project. Fixes applied: updated outdated CLI command, fixed broken doc links. Co-authored-by: jmagly --- docs/BEST_PRACTICES.md | 449 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 449 insertions(+) create mode 100644 docs/BEST_PRACTICES.md diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md new file mode 100644 index 0000000..b38382b --- /dev/null +++ b/docs/BEST_PRACTICES.md @@ -0,0 +1,449 @@ +# Best Practices for High-Quality Skills + +**Target Audience:** Anyone creating Claude skills | Already scraped documentation? Make it better! + +**Time:** 5-10 minutes to review | Apply as you build + +**Result:** Skills that Claude understands better and activates more reliably + +--- + +## Quick Checklist + +Before uploading a skill, check: + +- [ ] SKILL.md has clear "When to Use" triggers +- [ ] At least 5 code examples included +- [ ] Prerequisites documented (if any) +- [ ] Troubleshooting section present +- [ ] Quality score 90+ (Grade A) + +```bash +# Check your skill quality +skill-seekers quality output/myskill/ +``` + +--- + +## 1. Structure Your SKILL.md Clearly + +### Use Consistent Sections + +Claude looks for specific sections to understand your skill: + +```markdown +# Skill Name + +## Description +Brief explanation of what this skill enables. + +## When to Use This Skill +- User asks about [specific topic] +- User needs help with [specific task] +- User mentions [keywords] + +## Prerequisites +What needs to be true before using this skill. + +## Quick Reference +Most common commands or patterns. + +## Detailed Guide +Step-by-step instructions with examples. + +## Troubleshooting +Common issues and solutions. +``` + +### Why This Matters + +Claude uses the "When to Use" section to decide if your skill matches the user's question. Vague triggers = skill doesn't activate. + +**Bad Example:** +```markdown +## When to Use This Skill +Use this skill for API-related questions. +``` + +**Good Example:** +```markdown +## When to Use This Skill +- User asks about Steam Inventory API methods +- User needs to implement item drops in a Steam game +- User wants to grant promotional items to players +- User mentions: SteamInventory, GetAllItems, AddPromoItems +``` + +--- + +## 2. Include Real Code Examples + +Skills with 5+ code examples work significantly better. Claude learns patterns from examples. + +### What Works + +**Include a variety:** +- Basic usage (getting started) +- Common patterns (day-to-day use) +- Advanced usage (edge cases) +- Error handling (when things go wrong) + +**Example from a good SKILL.md:** +```markdown +## Quick Reference + +### Get All Items +```cpp +SteamInventoryResult_t resultHandle; +bool success = SteamInventory()->GetAllItems(&resultHandle); +``` + +### Grant Promotional Items +```cpp +void CInventory::GrantPromoItems() +{ + SteamItemDef_t newItems[2]; + newItems[0] = 110; + newItems[1] = 111; + SteamInventory()->AddPromoItems(&s_GenerateRequestResult, newItems, 2); +} +``` + +### Handle Async Results +```cpp +void OnSteamInventoryResult(SteamInventoryResultReady_t *pResult) +{ + if (pResult->m_result == k_EResultOK) { + // Process items + } +} +``` +``` + +### What to Avoid + +**Generic placeholder text:** +```markdown +## Quick Reference + +*Quick reference patterns will be added as you use the skill.* +``` + +**Code without context:** +```markdown +`GetAllItems()` +``` + +--- + +## 3. Document Prerequisites + +Claude can check conditions before proceeding. This prevents errors mid-execution. + +### Good Pattern + +```markdown +## Before You Start + +Make sure you have: +- [ ] Python 3.10+ installed +- [ ] API key set in environment (`export API_KEY=...`) +- [ ] Network access to api.example.com + +### Quick Check +```bash +python3 --version # Should show 3.10+ +echo $API_KEY # Should not be empty +curl api.example.com/health # Should return 200 +``` +``` + +### Why It Matters + +Without prerequisites, Claude might: +1. Start a complex workflow +2. Fail halfway through +3. Leave the user with a broken state + +With prerequisites, Claude can: +1. Check conditions first +2. Report what's missing +3. Guide the user to fix issues before starting + +--- + +## 4. Add Troubleshooting Sections + +Real-world usage hits errors. Document the common ones. + +### Template + +```markdown +## Troubleshooting + +### "Connection refused" error +**Cause:** Service not running or firewall blocking + +**Solution:** +1. Check if the service is running: `systemctl status myservice` +2. Verify firewall settings: `sudo ufw status` +3. Test connectivity: `curl -v https://api.example.com` + +### "Permission denied" error +**Cause:** Insufficient file permissions + +**Solution:** +1. Check file permissions: `ls -la /path/to/file` +2. Fix permissions: `chmod 644 /path/to/file` +3. Verify ownership: `chown user:group /path/to/file` + +### "Rate limited" error +**Cause:** Too many API requests + +**Solution:** +1. Wait 60 seconds before retrying +2. Implement exponential backoff in your code +3. Consider caching responses +``` + +### What to Include + +- Error message (exact text users see) +- Cause (why it happens) +- Solution (step-by-step fix) +- Prevention (how to avoid it) + +--- + +## 5. Organize Reference Files + +The `references/` directory should be easy to navigate. + +### Good Structure + +``` +output/myskill/ +├── SKILL.md # Main entry point +└── references/ + ├── index.md # Category overview + ├── getting_started.md # Installation, setup + ├── api_reference.md # API methods, classes + ├── guides.md # How-to tutorials + └── advanced.md # Complex scenarios +``` + +### Category Guidelines + +| Category | Contains | Keywords | +|----------|----------|----------| +| getting_started | Installation, setup, quickstart | intro, install, setup, quickstart | +| api_reference | Methods, classes, parameters | api, method, function, class, reference | +| guides | Step-by-step tutorials | guide, tutorial, how-to, example | +| concepts | Architecture, design patterns | concept, overview, architecture | +| advanced | Complex scenarios, internals | advanced, internal, extend | + +### Navigation Table in SKILL.md + +```markdown +## Navigation + +| Topic | File | Description | +|-------|------|-------------| +| Getting Started | references/getting_started.md | Installation and setup | +| API Reference | references/api_reference.md | Complete API documentation | +| Guides | references/guides.md | Step-by-step tutorials | +| Advanced | references/advanced.md | Complex scenarios | +``` + +--- + +## 6. Run Quality Checks + +Always check quality before uploading: + +```bash +# Check quality score +skill-seekers quality output/myskill/ + +# Expected output: +# ✅ Grade: A (Score: 95) +# ✅ No errors +# ⚠️ 1 warning: Consider adding more code examples +``` + +### Quality Targets + +| Grade | Score | Status | +|-------|-------|--------| +| A | 90-100 | Ready to upload | +| B | 80-89 | Good, minor improvements possible | +| C | 70-79 | Review warnings before uploading | +| D | 60-69 | Needs work | +| F | < 60 | Significant issues | + +### Common Issues + +**"Missing SKILL.md"** +- Run the scraper first +- Or create manually + +**"No code examples found"** +- Add code blocks to SKILL.md +- Run enhancement: `skill-seekers enhance output/myskill/` + +**"Generic description"** +- Rewrite "When to Use" section +- Add specific keywords and use cases + +--- + +## 7. Test Your Skill + +Before uploading, test with Claude: + +### Manual Testing + +1. Upload the skill to Claude +2. Ask a question your skill should answer +3. Check if Claude activates the skill +4. Verify the response uses skill content + +### Test Questions + +For a Steam Inventory skill: +``` +"How do I get all items in a player's Steam inventory?" +"What's the API call for granting promotional items?" +"Show me how to handle async inventory results" +``` + +### What to Look For + +**Good activation:** +- Claude references your skill +- Response includes examples from your SKILL.md +- Specific, accurate information + +**Poor activation:** +- Claude gives generic answer +- No skill reference +- Information doesn't match your docs + +--- + +## Real-World Example + +### Before Improvement + +```markdown +# React Skill + +## Description +React documentation. + +## When to Use +For React questions. + +## Quick Reference +See references. +``` + +**Quality Score:** 45 (Grade F) + +### After Improvement + +```markdown +# React Skill + +## Description +Complete React 18+ documentation including hooks, components, and best practices. + +## When to Use This Skill +- User asks about React hooks (useState, useEffect, useContext) +- User needs help with React component lifecycle +- User wants to implement React patterns (render props, HOCs, custom hooks) +- User mentions: React, JSX, virtual DOM, fiber, concurrent mode + +## Prerequisites +- Node.js 16+ for development +- Basic JavaScript/ES6 knowledge + +## Quick Reference + +### useState Hook +```jsx +const [count, setCount] = useState(0); +``` + +### useEffect Hook +```jsx +useEffect(() => { + document.title = `Count: ${count}`; +}, [count]); +``` + +### Custom Hook +```jsx +function useWindowSize() { + const [size, setSize] = useState({ width: 0, height: 0 }); + useEffect(() => { + const handleResize = () => { + setSize({ width: window.innerWidth, height: window.innerHeight }); + }; + window.addEventListener('resize', handleResize); + handleResize(); + return () => window.removeEventListener('resize', handleResize); + }, []); + return size; +} +``` + +## Troubleshooting + +### "Invalid hook call" +**Cause:** Hook called outside component or conditionally + +**Solution:** +1. Only call hooks at top level of function components +2. Don't call hooks inside loops or conditions +3. Check for multiple React copies: `npm ls react` +``` + +**Quality Score:** 94 (Grade A) + +--- + +## Summary + +| Practice | Why It Matters | Quick Check | +|----------|---------------|-------------| +| Clear structure | Claude knows where to look | Has all standard sections? | +| Code examples (5+) | Claude learns patterns | Count code blocks | +| Prerequisites | Prevents mid-task failures | Prerequisites section exists? | +| Troubleshooting | Handles real-world errors | Common errors documented? | +| Organized references | Easy navigation | Categories make sense? | +| Quality check | Catches issues early | Score 90+? | +| Testing | Confirms it works | Claude activates skill? | + +**Final command before upload:** +```bash +skill-seekers quality output/myskill/ +``` + +That's it! Follow these practices and your skills will work better with Claude. + +--- + +## See Also + +- [Enhancement Guide](features/ENHANCEMENT.md) - AI-powered SKILL.md improvement +- [Upload Guide](guides/UPLOAD_GUIDE.md) - How to upload skills to Claude +- [CLI Reference](reference/CLI_REFERENCE.md) - Complete command reference + +--- + +## Contributing + +This guide was contributed by the [AI Writing Guide](https://github.com/jmagly/ai-writing-guide) project, which uses Skill Seekers for documentation-to-skill conversion. Best practices here are informed by research on production-grade agentic workflows. + +Found an issue or want to improve this guide? PRs welcome!