Published on

Advanced Skill Configuration: Multi-File Skills and Progressive Disclosure

Authors
  • avatar
    Name
    Anablock
    Twitter

    AI Insights & Innovations

Claude Advanced Skills

Advanced Skill Configuration: Multi-File Skills and Progressive Disclosure

A basic skill works with just a name and description, but there are several advanced techniques that can make your skills much more effective in Claude Code. This guide covers the key fields, best practices for descriptions, tool restrictions, and how to structure larger skills efficiently.

Skill Metadata Fields

The agent skills open standard supports several fields in the SKILL.md frontmatter. Two are required, and the rest are optional:

name (required) — Identifies your skill. Use lowercase letters, numbers, and hyphens only. Maximum 64 characters. Should match your directory name.

description (required) — Tells Claude when to use the skill. Maximum 1,024 characters. This is the most important field because Claude uses it for matching.

allowed-tools (optional) — Restricts which tools Claude can use when the skill is active.

model (optional) — Specifies which Claude model to use for the skill.

Writing Effective Descriptions

Be explicit with your instructions. If someone told you "your job is to help with docs," you wouldn't know what to do — and Claude thinks the same way.

A good description answers two questions:

  1. What does the skill do?
  2. When should Claude use it?

If your skill isn't triggering when you expect it to, try adding more keywords that match how you actually phrase your requests. The description is what Claude uses to decide whether a skill is relevant, so the language matters.

Example: Weak vs. Strong Descriptions

❌ Weak: "Helps with testing"

✅ Strong: "Writes unit tests for React components. Use when creating tests, writing test files, testing a component, or when the user asks to add test coverage."

The strong description includes:

  • What it does (writes unit tests for React components)
  • Multiple trigger phrases (creating tests, writing test files, testing a component)
  • Natural language variations ("when the user asks to add test coverage")

Restricting Tools with allowed-tools

Sometimes you want a skill that can only read files, not modify them. This is useful for security-sensitive workflows, read-only tasks, or any situation where you want guardrails.

---
name: codebase-onboarding
description: Helps new developers understand how the system works. Use when onboarding, explaining architecture, or giving codebase tours.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

When helping someone understand the codebase:

1. Start by reading the README and main entry points
2. Use grep to find relevant code patterns
3. Explain the architecture and key components
4. Never modify files — this is a read-only skill

In this example, the allowed-tools field is set to Read, Grep, Glob, Bash. When this skill is active, Claude can only use those tools without asking permission — no editing, no writing.

Available tool categories:

  • Read — Read file contents
  • Grep — Search file contents
  • Glob — List files matching patterns
  • Bash — Execute shell commands
  • Edit — Modify files
  • Write — Create new files

If you omit allowed-tools entirely, the skill doesn't restrict anything. Claude uses its normal permission model.

When to Use Tool Restrictions

Read-only analysis:

allowed-tools: Read, Grep, Glob

Perfect for code reviews, security audits, or documentation generation where you never want to modify source files.

Safe exploration:

allowed-tools: Read, Grep, Glob, Bash

Allows running commands to check environment state, but prevents file modifications.

Full access: Omit allowed-tools entirely for skills that need to create, edit, and manage files.

Progressive Disclosure

Skills share Claude's context window with your conversation. When Claude activates a skill, it loads the contents of that SKILL.md into context. But sometimes you need references, examples, or utility scripts that the skill depends on.

Cramming everything into one 2,000-line file has two problems:

  1. It takes up a lot of context window space
  2. It's not fun to maintain

Progressive disclosure solves this. Keep essential instructions in SKILL.md and put detailed reference material in separate files that Claude reads only when needed.

Organizing Multi-File Skills

The open standard suggests organizing your skill directory with:

~/.claude/skills/architecture-guide/
├── SKILL.md
├── scripts/
│   ├── validate-env.sh
│   └── generate-diagram.py
├── references/
│   ├── architecture-guide.md
│   ├── api-patterns.md
│   └── database-schema.md
└── assets/
    ├── component-template.tsx
    └── test-template.spec.ts

Example: Architecture Guide Skill

---
name: architecture-guide
description: Explains system architecture and helps developers understand how components interact. Use when someone asks about system design, architecture, or how things fit together.
allowed-tools: Read, Grep, Glob, Bash
---

When explaining the architecture:

1. If the question is about overall system design, read `references/architecture-guide.md`
2. If the question is about API patterns, read `references/api-patterns.md`
3. If the question is about database structure, read `references/database-schema.md`
4. Use grep to find relevant code examples
5. Explain clearly with examples from the actual codebase

Never modify files — this is a read-only skill for understanding the system.

In this example, Claude reads architecture-guide.md only when someone asks about system design. If they're asking where to add a component, it never loads that file. It's like having a table of contents in the context window rather than the entire document.

Best Practices for Progressive Disclosure

Keep SKILL.md under 500 lines
If you're exceeding that, consider whether the content should be split into separate reference files.

Use clear conditional instructions
"If the user asks about X, read references/x-guide.md" — this tells Claude exactly when to load additional context.

Group related content
Put all API documentation in one file, all database schemas in another, all deployment guides in a third.

Link, don't duplicate
If multiple skills need the same reference material, put it in a shared location and link to it from both skills.

Using Scripts Efficiently

Scripts in your skill directory can run without loading their contents into context. The script executes and only the output consumes tokens. The key instruction to include in your SKILL.md is to tell Claude to run the script, not read it.

Example: Environment Validation Skill

---
name: env-check
description: Validates development environment setup. Use when checking dependencies, verifying installation, or troubleshooting environment issues.
allowed-tools: Bash, Read
---

When validating the environment:

1. Run `scripts/validate-env.sh` (do not read it — just execute it)
2. Review the output for any missing dependencies
3. If issues are found, suggest installation commands
4. Confirm all required tools are at the correct versions

scripts/validate-env.sh:

#!/bin/bash

echo "Checking Node.js version..."
node --version || echo "❌ Node.js not found"

echo "Checking npm version..."
npm --version || echo "❌ npm not found"

echo "Checking Docker..."
docker --version || echo "❌ Docker not found"

echo "Checking PostgreSQL..."
psql --version || echo "❌ PostgreSQL not found"

echo "✅ Environment check complete"

This is particularly useful for:

  • Environment validation — Check dependencies without cluttering context
  • Data transformations — Consistent processing that's more reliable as tested code
  • Operations — Tasks that are better as scripts than generated code

Script Best Practices

Make scripts executable:

chmod +x scripts/validate-env.sh

Include error handling:

set -e  # Exit on error
set -u  # Exit on undefined variable

Output clear results: Scripts should produce human-readable output that Claude can interpret and explain to the user.

Keep scripts focused: One script = one task. Don't create monolithic scripts that do everything.

Real-World Multi-File Skill Example

Let's build a comprehensive code review skill that uses all these techniques:

Directory Structure

~/.claude/skills/code-review/
├── SKILL.md
├── scripts/
│   ├── run-linter.sh
│   └── check-tests.sh
├── references/
│   ├── security-checklist.md
│   ├── performance-guide.md
│   └── style-guide.md
└── assets/
    └── review-template.md

SKILL.md

---
name: code-review
description: Performs comprehensive code reviews. Use when reviewing code, checking pull requests, auditing changes, or when the user asks for a code review.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

When performing a code review:

1. Run `git diff main...HEAD` to see all changes
2. Run `scripts/run-linter.sh` to check for style issues
3. Run `scripts/check-tests.sh` to verify test coverage
4. Review the code for:
   - Security issues (read `references/security-checklist.md` if needed)
   - Performance concerns (read `references/performance-guide.md` if needed)
   - Style violations (read `references/style-guide.md` if needed)
5. Format findings using `assets/review-template.md`
6. Provide actionable feedback with specific line numbers

Never modify files during a review — this is a read-only analysis skill.

scripts/run-linter.sh

#!/bin/bash
set -e

echo "Running ESLint..."
npx eslint . --ext .js,.jsx,.ts,.tsx || true

echo "Running Prettier check..."
npx prettier --check "**/*.{js,jsx,ts,tsx,json,md}" || true

echo "✅ Linting complete"

scripts/check-tests.sh

#!/bin/bash
set -e

echo "Checking test coverage..."
npm test -- --coverage --silent || true

echo "✅ Test check complete"

references/security-checklist.md

# Security Review Checklist

## Authentication & Authorization
- [ ] Are authentication tokens stored securely?
- [ ] Is authorization checked on all protected routes?
- [ ] Are user permissions validated server-side?

## Input Validation
- [ ] Are all user inputs sanitized?
- [ ] Is SQL injection prevented (parameterized queries)?
- [ ] Is XSS prevented (output encoding)?

## Data Protection
- [ ] Are passwords hashed (bcrypt, Argon2)?
- [ ] Is sensitive data encrypted at rest?
- [ ] Are API keys stored in environment variables?

## Dependencies
- [ ] Are dependencies up to date?
- [ ] Are there known CVEs in dependencies?
- [ ] Is `npm audit` clean?

assets/review-template.md

# Code Review: [PR Title]

## Summary
[One-sentence summary of what this PR does]

## Security
- ✅ No security issues found
- ⚠️ [Issue description with line number]

## Performance
- ✅ No performance concerns
- ⚠️ [Issue description with line number]

## Style
- ✅ Follows style guide
- ⚠️ [Issue description with line number]

## Tests
- ✅ Adequate test coverage
- ⚠️ Missing tests for [feature]

## Recommendations
1. [Specific actionable feedback]
2. [Specific actionable feedback]

## Approval Status
- [ ] Approved
- [ ] Approved with minor changes
- [ ] Changes requested

Model Selection

The model field lets you specify which Claude model to use for a skill:

---
name: quick-refactor
description: Fast code refactoring for simple changes
model: haiku
---

When to use different models:

Haiku — Fast, lightweight tasks:

  • Simple refactoring
  • Code formatting
  • Quick searches
  • Routine operations

Sonnet (default) — Balanced performance:

  • Code reviews
  • Documentation generation
  • Most general-purpose skills

Opus — Complex reasoning:

  • Architecture design
  • Security audits
  • Complex debugging
  • Multi-step workflows

If you omit the model field, Claude uses Sonnet by default.

Context Window Management

Every skill you activate consumes part of Claude's context window. Here's how to keep your skills efficient:

1. Keep SKILL.md Concise

Target: Under 500 lines

If your SKILL.md is growing beyond 500 lines, it's time to split content into reference files.

2. Use Conditional Loading

If the user asks about API design, read `references/api-guide.md`
If the user asks about database schema, read `references/schema-guide.md`

This ensures Claude only loads what's needed for the current task.

3. Prefer Scripts Over Instructions

Instead of:

To check dependencies:
1. Run `node --version` and verify it's >= 18.0.0
2. Run `npm --version` and verify it's >= 9.0.0
3. Run `docker --version` and verify it's >= 20.0.0
4. Check that PostgreSQL is installed
5. Verify all environment variables are set

Use:

To check dependencies, run `scripts/validate-env.sh`

The script executes and only the output consumes tokens, not the script contents.

4. Link to External Documentation

For stable external references, link to URLs rather than duplicating content:

For React best practices, refer to: https://react.dev/learn
For TypeScript patterns, refer to: https://www.typescriptlang.org/docs/

Advanced Example: Full-Stack Development Skill

Here's a production-ready skill that uses all advanced features:

Directory Structure

~/.claude/skills/fullstack-dev/
├── SKILL.md
├── scripts/
│   ├── setup-db.sh
│   ├── run-migrations.sh
│   ├── seed-data.sh
│   └── check-env.sh
├── references/
│   ├── api-conventions.md
│   ├── database-schema.md
│   ├── frontend-patterns.md
│   └── deployment-guide.md
└── assets/
    ├── component-template.tsx
    ├── api-route-template.ts
    └── migration-template.sql

SKILL.md

---
name: fullstack-dev
description: Full-stack development assistant for React/Node.js/PostgreSQL applications. Use when building features, creating APIs, setting up databases, or working on full-stack tasks.
model: sonnet
---

When working on full-stack development:

## Environment Setup
- To validate environment, run `scripts/check-env.sh`
- To setup database, run `scripts/setup-db.sh`
- To run migrations, run `scripts/run-migrations.sh`
- To seed test data, run `scripts/seed-data.sh`

## API Development
- Read `references/api-conventions.md` for API design patterns
- Use `assets/api-route-template.ts` as a starting point for new endpoints
- Follow RESTful conventions
- Include input validation and error handling

## Frontend Development
- Read `references/frontend-patterns.md` for component patterns
- Use `assets/component-template.tsx` for new components
- Follow React best practices
- Ensure accessibility (ARIA labels, keyboard navigation)

## Database Work
- Read `references/database-schema.md` for current schema
- Use `assets/migration-template.sql` for new migrations
- Always create migrations for schema changes
- Test migrations with seed data

## Deployment
- Read `references/deployment-guide.md` before deploying
- Verify all environment variables are set
- Run tests before deployment
- Check database migrations are applied

scripts/check-env.sh

#!/bin/bash
set -e

echo "🔍 Checking development environment..."
echo ""

# Node.js
if command -v node &> /dev/null; then
    NODE_VERSION=$(node --version)
    echo "✅ Node.js: $NODE_VERSION"
else
    echo "❌ Node.js not found"
fi

# npm
if command -v npm &> /dev/null; then
    NPM_VERSION=$(npm --version)
    echo "✅ npm: $NPM_VERSION"
else
    echo "❌ npm not found"
fi

# PostgreSQL
if command -v psql &> /dev/null; then
    PSQL_VERSION=$(psql --version)
    echo "✅ PostgreSQL: $PSQL_VERSION"
else
    echo "❌ PostgreSQL not found"
fi

# Docker
if command -v docker &> /dev/null; then
    DOCKER_VERSION=$(docker --version)
    echo "✅ Docker: $DOCKER_VERSION"
else
    echo "❌ Docker not found"
fi

echo ""
echo "✅ Environment check complete"

references/api-conventions.md

# API Conventions

## Endpoint Naming
- Use plural nouns: `/api/users`, `/api/posts`
- Use kebab-case for multi-word resources: `/api/blog-posts`
- Nest resources logically: `/api/users/:id/posts`

## HTTP Methods
- `GET` — Retrieve resources
- `POST` — Create new resources
- `PUT` — Update entire resource
- `PATCH` — Update partial resource
- `DELETE` — Remove resource

## Response Format
```json
{
  "data": { ... },
  "meta": {
    "page": 1,
    "total": 100
  },
  "errors": []
}

Error Handling

  • Return appropriate HTTP status codes
  • Include error messages in errors array
  • Log errors server-side
  • Never expose stack traces in production

## Troubleshooting Multi-File Skills

### Skill Not Loading Reference Files

**Problem**: Claude isn't reading your reference files when expected.

**Solution**: Make your conditional instructions more explicit:

❌ **Vague**: "Use the security guide when needed"

✅ **Explicit**: "If the user asks about security, authentication, or vulnerabilities, read `references/security-checklist.md`"

### Scripts Not Executing

**Problem**: Scripts fail to run or produce errors.

**Solution**:
1. Verify scripts are executable: `chmod +x scripts/*.sh`
2. Check shebang line: `#!/bin/bash`
3. Test scripts manually before adding to skill
4. Include error handling: `set -e`

### Context Window Overflow

**Problem**: Skill is too large and causes context issues.

**Solution**:
1. Split `SKILL.md` into smaller reference files
2. Use scripts instead of inline instructions
3. Link to external documentation instead of duplicating
4. Remove redundant examples

## Skill Metadata Reference

### Complete Frontmatter Example

```markdown
---
name: security-audit
description: Performs comprehensive security audits of code. Use when reviewing security, checking for vulnerabilities, auditing authentication, or when the user asks for a security review.
allowed-tools: Read, Grep, Glob, Bash
model: opus
---

Field Constraints

| Field | Required | Max Length | Format | |-------|----------|------------|--------| | name | Yes | 64 chars | lowercase, numbers, hyphens | | description | Yes | 1,024 chars | Plain text | | allowed-tools | No | N/A | Comma-separated list | | model | No | N/A | haiku, sonnet, opus |

Lesson Reflection

Before moving on, consider these questions:

Think about a skill you'd like to build that involves multiple files. How would you structure the SKILL.md versus supporting reference files? What would go in scripts vs. references vs. assets?

Are there workflows in your team where restricting tool access with allowed-tools would add an important safety layer? Code reviews? Security audits? Documentation generation?

How would progressive disclosure help with your largest or most complex skill? What content could be moved to reference files that Claude only loads when needed?

What's Next

In the next lesson, we'll compare skills to the other ways you can customize Claude Code — CLAUDE.md, subagents, hooks, and MCP servers — so you can choose the right tool for each situation.

Quick Reference

Skill Metadata Fields

---
name: skill-name
description: What it does and when to use it
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Directory Structure

skill-name/
├── SKILL.md          # Core instructions (<500 lines)
├── scripts/          # Executable scripts
├── references/       # Detailed documentation
└── assets/           # Templates and resources

Tool Categories

  • Read — Read files
  • Grep — Search content
  • Glob — List files
  • Bash — Run commands
  • Edit — Modify files
  • Write — Create files

Model Options

  • haiku — Fast, lightweight
  • sonnet — Balanced (default)
  • opus — Complex reasoning

Master these advanced techniques and you'll build skills that are powerful, maintainable, and context-efficient. Start with a simple skill and gradually add complexity as you discover what works best for your workflow.