skill-seekers-reference/docs/BEST_PRACTICES.md

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)

# 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:

# 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:

## When to Use This Skill
Use this skill for API-related questions.

Good Example:

## 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:

## Quick Reference

### Get All Items
```cpp
SteamInventoryResult_t resultHandle;
bool success = SteamInventory()->GetAllItems(&resultHandle);

Grant Promotional Items

void CInventory::GrantPromoItems()
{
    SteamItemDef_t newItems[2];
    newItems[0] = 110;
    newItems[1] = 111;
    SteamInventory()->AddPromoItems(&s_GenerateRequestResult, newItems, 2);
}

Handle Async Results

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:

`GetAllItems()`

---

3. Document Prerequisites

Claude can check conditions before proceeding. This prevents errors mid-execution.

Good Pattern

## 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

## 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:

# 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

# React Skill

## Description
React documentation.

## When to Use
For React questions.

## Quick Reference
See references.

Quality Score: 45 (Grade F)

After Improvement

# 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

useEffect(() => {
  document.title = `Count: ${count}`;
}, [count]);

Custom Hook

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.

---

8. Tips for Specific Source Types

Skill Seekers supports 17 source types. Here are tips for getting the best results from each category:

Documentation (Web)

• Always test CSS selectors before large scrapes: skill-seekers scrape --max-pages 3 --verbose
• Use --async for large sites (2-3x faster)

GitHub Repos

• Use --analysis-depth c3x for deep analysis (patterns, tests, architecture)
• Set GITHUB_TOKEN to avoid rate limits

PDFs & Office Documents (PDF, Word, EPUB, PPTX)

• Use --enable-ocr for scanned PDFs
• For Word/PPTX, embedded images are extracted automatically; add --extract-images for PDFs
• EPUB works best with DRM-free files

Video

• Run skill-seekers video --setup first to install GPU-optimized dependencies
• YouTube and Vimeo URLs are auto-detected; local video files also work

Jupyter Notebooks

• Ensure notebooks are saved (unsaved cell outputs won't be captured)
• Both code cells and markdown cells are extracted

OpenAPI/Swagger Specs

• Both YAML and JSON specs are supported (OpenAPI 3.x and Swagger 2.0)
• Endpoints, schemas, and examples are parsed into structured API reference

AsciiDoc & Man Pages

• AsciiDoc requires asciidoctor (install via your package manager or gem)
• Man pages in sections .1 through .8 are supported

RSS/Atom Feeds

• Useful for converting blog posts and changelogs into skills
• Set --max-items to limit how many entries are extracted

Confluence & Notion

• API mode requires authentication tokens (see FAQ for setup)
• Export directory mode works offline with HTML/Markdown exports

Slack & Discord

• Use official export tools (Slack Workspace Export, DiscordChatExporter)
• Specify --platform slack or --platform discord explicitly

---

See Also

• Enhancement Guide - AI-powered SKILL.md improvement
• Upload Guide - How to upload skills to Claude
• CLI Reference - Complete command reference

---

Contributing

This guide was contributed by the 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!