docs: add best practices guide for high-quality skills (#206)

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 <jmagly@users.noreply.github.com>
2026-03-15 02:51:02 +03:00
parent 7185531f94
commit 64403a3686
1 changed files with 449 additions and 0 deletions
--- a/docs/BEST_PRACTICES.md
+++ 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!