Init
This commit is contained in:
yusyus
250
docs/ENHANCEMENT.md
Normal file
250
docs/ENHANCEMENT.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# AI-Powered SKILL.md Enhancement
|
||||
|
||||
Two scripts are available to dramatically improve your SKILL.md file:
|
||||
1. **`enhance_skill_local.py`** - Uses Claude Code Max (no API key, **recommended**)
|
||||
2. **`enhance_skill.py`** - Uses Anthropic API (~$0.15-$0.30 per skill)
|
||||
|
||||
Both analyze reference documentation and extract the best examples and guidance.
|
||||
|
||||
## Why Use Enhancement?
|
||||
|
||||
**Problem:** The auto-generated SKILL.md is often too generic:
|
||||
- Empty Quick Reference section
|
||||
- No practical code examples
|
||||
- Generic "When to Use" triggers
|
||||
- Doesn't highlight key features
|
||||
|
||||
**Solution:** Let Claude read your reference docs and create a much better SKILL.md with:
|
||||
- ✅ Best code examples extracted from documentation
|
||||
- ✅ Practical quick reference with real patterns
|
||||
- ✅ Domain-specific guidance
|
||||
- ✅ Clear navigation tips
|
||||
- ✅ Key concepts explained
|
||||
|
||||
## Quick Start (LOCAL - No API Key)
|
||||
|
||||
**Recommended for Claude Code Max users:**
|
||||
|
||||
```bash
|
||||
# Option 1: Standalone enhancement
|
||||
python3 enhance_skill_local.py output/steam-inventory/
|
||||
|
||||
# Option 2: Integrated with scraper
|
||||
python3 doc_scraper.py --config configs/steam-inventory.json --enhance-local
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Opens new terminal window
|
||||
2. Runs Claude Code with enhancement prompt
|
||||
3. Claude analyzes reference files (~15-20K chars)
|
||||
4. Generates enhanced SKILL.md (30-60 seconds)
|
||||
5. Terminal auto-closes when done
|
||||
|
||||
**Requirements:**
|
||||
- Claude Code Max plan (you're already using it!)
|
||||
- macOS (auto-launch works) or manual terminal run on other OS
|
||||
|
||||
## API-Based Enhancement (Alternative)
|
||||
|
||||
**If you prefer API-based approach:**
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip3 install anthropic
|
||||
```
|
||||
|
||||
### Setup API Key
|
||||
|
||||
```bash
|
||||
# Option 1: Environment variable (recommended)
|
||||
export ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Option 2: Pass directly with --api-key
|
||||
python3 enhance_skill.py output/react/ --api-key sk-ant-...
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Standalone enhancement
|
||||
python3 enhance_skill.py output/steam-inventory/
|
||||
|
||||
# Integrated with scraper
|
||||
python3 doc_scraper.py --config configs/steam-inventory.json --enhance
|
||||
|
||||
# Dry run (see what would be done)
|
||||
python3 enhance_skill.py output/react/ --dry-run
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Reads reference files** (api_reference.md, webapi.md, etc.)
|
||||
2. **Sends to Claude** with instructions to:
|
||||
- Extract 5-10 best code examples
|
||||
- Create practical quick reference
|
||||
- Write domain-specific "When to Use" triggers
|
||||
- Add helpful navigation guidance
|
||||
3. **Backs up original** SKILL.md to SKILL.md.backup
|
||||
4. **Saves enhanced version** as new SKILL.md
|
||||
|
||||
## Example Enhancement
|
||||
|
||||
### Before (Auto-Generated)
|
||||
```markdown
|
||||
## Quick Reference
|
||||
|
||||
### Common Patterns
|
||||
|
||||
*Quick reference patterns will be added as you use the skill.*
|
||||
```
|
||||
|
||||
### After (AI-Enhanced)
|
||||
```markdown
|
||||
## Quick Reference
|
||||
|
||||
### Common API Patterns
|
||||
|
||||
**Granting promotional items:**
|
||||
```cpp
|
||||
void CInventory::GrantPromoItems()
|
||||
{
|
||||
SteamItemDef_t newItems[2];
|
||||
newItems[0] = 110;
|
||||
newItems[1] = 111;
|
||||
SteamInventory()->AddPromoItems( &s_GenerateRequestResult, newItems, 2 );
|
||||
}
|
||||
```
|
||||
|
||||
**Getting all items in player inventory:**
|
||||
```cpp
|
||||
SteamInventoryResult_t resultHandle;
|
||||
bool success = SteamInventory()->GetAllItems( &resultHandle );
|
||||
```
|
||||
[... 8 more practical examples ...]
|
||||
```
|
||||
|
||||
## Cost Estimate
|
||||
|
||||
- **Input**: ~50,000-100,000 tokens (reference docs)
|
||||
- **Output**: ~4,000 tokens (enhanced SKILL.md)
|
||||
- **Model**: claude-sonnet-4-20250514
|
||||
- **Estimated cost**: $0.15-$0.30 per skill
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No API key provided"
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=sk-ant-...
|
||||
# or
|
||||
python3 enhance_skill.py output/react/ --api-key sk-ant-...
|
||||
```
|
||||
|
||||
### "No reference files found"
|
||||
Make sure you've run the scraper first:
|
||||
```bash
|
||||
python3 doc_scraper.py --config configs/react.json
|
||||
```
|
||||
|
||||
### "anthropic package not installed"
|
||||
```bash
|
||||
pip3 install anthropic
|
||||
```
|
||||
|
||||
### Don't like the result?
|
||||
```bash
|
||||
# Restore original
|
||||
mv output/steam-inventory/SKILL.md.backup output/steam-inventory/SKILL.md
|
||||
|
||||
# Try again (it may generate different content)
|
||||
python3 enhance_skill.py output/steam-inventory/
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Run after scraping completes** - Enhancement works best with complete reference docs
|
||||
2. **Review the output** - AI is good but not perfect, check the generated SKILL.md
|
||||
3. **Keep the backup** - Original is saved as SKILL.md.backup
|
||||
4. **Re-run if needed** - Each run may produce slightly different results
|
||||
5. **Works offline after first run** - Reference files are local
|
||||
|
||||
## Real-World Results
|
||||
|
||||
**Test Case: steam-economy skill**
|
||||
- **Before:** 75 lines, generic template, empty Quick Reference
|
||||
- **After:** 570 lines, 10 practical API examples, key concepts explained
|
||||
- **Time:** 60 seconds
|
||||
- **Quality Rating:** 9/10
|
||||
|
||||
The LOCAL enhancement successfully:
|
||||
- Extracted best HTTP/JSON examples from 24 pages of documentation
|
||||
- Explained domain concepts (Asset Classes, Context IDs, Transaction Lifecycle)
|
||||
- Created navigation guidance for beginners through advanced users
|
||||
- Added best practices for security, economy design, and API integration
|
||||
|
||||
## Limitations
|
||||
|
||||
**LOCAL Enhancement (`enhance_skill_local.py`):**
|
||||
- Requires Claude Code Max plan
|
||||
- macOS auto-launch only (manual on other OS)
|
||||
- Opens new terminal window
|
||||
- Takes ~60 seconds
|
||||
|
||||
**API Enhancement (`enhance_skill.py`):**
|
||||
- Requires Anthropic API key (paid)
|
||||
- Cost: ~$0.15-$0.30 per skill
|
||||
- Limited to ~100K tokens of reference input
|
||||
|
||||
**Both:**
|
||||
- May occasionally miss the best examples
|
||||
- Can't understand context beyond the reference docs
|
||||
- Doesn't modify reference files (only SKILL.md)
|
||||
|
||||
## Enhancement Options Comparison
|
||||
|
||||
| Aspect | Manual Edit | LOCAL Enhancement | API Enhancement |
|
||||
|--------|-------------|-------------------|-----------------|
|
||||
| Time | 15-30 minutes | 30-60 seconds | 30-60 seconds |
|
||||
| Code examples | You pick | AI picks best | AI picks best |
|
||||
| Quick reference | Write yourself | Auto-generated | Auto-generated |
|
||||
| Domain guidance | Your knowledge | From docs | From docs |
|
||||
| Consistency | Varies | Consistent | Consistent |
|
||||
| Cost | Free (your time) | Free (Max plan) | ~$0.20 per skill |
|
||||
| Setup | None | None | API key needed |
|
||||
| Quality | High (if expert) | 9/10 | 9/10 |
|
||||
| **Recommended?** | For experts only | ✅ **Yes** | If no Max plan |
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use enhancement when:**
|
||||
- You want high-quality SKILL.md quickly
|
||||
- Working with large documentation (50+ pages)
|
||||
- Creating skills for unfamiliar frameworks
|
||||
- Need practical code examples extracted
|
||||
- Want consistent quality across multiple skills
|
||||
|
||||
**Skip enhancement when:**
|
||||
- Budget constrained (use manual editing)
|
||||
- Very small documentation (<10 pages)
|
||||
- You know the framework intimately
|
||||
- Documentation has no code examples
|
||||
|
||||
## Advanced: Customization
|
||||
|
||||
To customize how Claude enhances the SKILL.md, edit `enhance_skill.py` and modify the `_build_enhancement_prompt()` method around line 130.
|
||||
|
||||
Example customization:
|
||||
```python
|
||||
prompt += """
|
||||
ADDITIONAL REQUIREMENTS:
|
||||
- Focus on security best practices
|
||||
- Include performance tips
|
||||
- Add troubleshooting section
|
||||
"""
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Main documentation
|
||||
- [CLAUDE.md](CLAUDE.md) - Architecture guide
|
||||
- [doc_scraper.py](../doc_scraper.py) - Main scraping tool
|
||||
Reference in New Issue
Block a user