architecture/old2/skills/examples/progressive-disclosure.md

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

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