# 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