Hugo Nijhuis
f424a7f992
Updates capability-writing skill with progressive disclosure structure based on Anthropic's January 2025 documentation. Implements Haiku-first approach (12x cheaper, 2-5x faster than Sonnet). Key changes: - Add 5 core principles: conciseness, progressive disclosure, script bundling, degrees of freedom, and Haiku-first model selection - Restructure with best-practices.md, templates/, examples/, and reference/ - Create 4 templates: user-invocable skill, background skill, agent, helper script - Add 3 examples: simple workflow, progressive disclosure, with scripts - Add 3 reference docs: frontmatter fields, model selection, anti-patterns - Update create-capability to analyze complexity and recommend structures - Default all new skills/agents to Haiku unless justified Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
3.4 KiB
3.4 KiB
Example: Progressive Disclosure Skill
A skill that uses reference files to keep the main SKILL.md concise.
Structure
skills/database-query/
├── SKILL.md (~200 lines)
├── reference/
│ ├── schemas.md (table schemas)
│ ├── common-queries.md (frequently used queries)
│ └── optimization-tips.md (performance guidance)
└── examples/
├── simple-select.md
└── complex-join.md
When to Use
- Skill content would be >500 lines
- Multiple domains or topics
- Reference documentation is large
- Want to keep main workflow concise
Example: database-query (main SKILL.md)
---
name: database-query
description: >
Help users query the PostgreSQL database with proper schemas and optimization.
Use when user needs to write SQL queries or mentions database/tables.
user-invocable: false
---
# Database Query Helper
Help write efficient, correct SQL queries for our PostgreSQL database.
## Quick Start
\`\`\`sql
SELECT id, name, created_at
FROM users
WHERE status = 'active'
LIMIT 10;
\`\`\`
## Table Schemas
We have 3 main schemas:
- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
## Common Queries
For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
- User activity reports
- Sales summaries
- Inventory status
## Writing Queries
1. **Identify tables**: Which schemas does this query need?
2. **Check schema**: Load relevant schema from reference
3. **Write query**: Use proper column names and types
4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
## Examples
- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
Example: reference/schemas.md
# Database Schemas
## Users
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| email | VARCHAR(255) | Unique email |
| name | VARCHAR(100) | Display name |
| status | ENUM('active','inactive','banned') | Account status |
| created_at | TIMESTAMP | Account creation |
| updated_at | TIMESTAMP | Last update |
## Products
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| name | VARCHAR(200) | Product name |
| price | DECIMAL(10,2) | Price in USD |
| inventory | INTEGER | Stock count |
| category_id | UUID | FK to categories |
## Orders
[...more tables...]
Why This Works
- Main file stays concise (~200 lines)
- Details load on-demand: schemas.md loads when user asks about specific table
- Fast for common cases: Simple queries don't need reference files
- Scalable: Can add more schemas without bloating main file
Loading Pattern
- User: "Show me all active users"
- Claude reads SKILL.md (sees Users schema reference)
- Claude: "I'll load the users schema to get column names"
- Claude reads reference/schemas.md#users
- Claude writes correct query
What Makes It Haiku-Friendly
- ✓ Main workflow is simple ("identify → check schema → write query")
- ✓ Reference files provide facts, not reasoning
- ✓ Clear pointers to where details are
- ✓ Examples show patterns