130 lines
3.4 KiB
Markdown
130 lines
3.4 KiB
Markdown
# 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)
|
|
|
|
```markdown
|
|
---
|
|
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
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
1. User: "Show me all active users"
|
|
2. Claude reads SKILL.md (sees Users schema reference)
|
|
3. Claude: "I'll load the users schema to get column names"
|
|
4. Claude reads reference/schemas.md#users
|
|
5. 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
|