When to Split a Skill into Multiple Files vs Keeping in SKILL.md: Complete Guide

Keep your skill in a single SKILL.md file if it stays under 100 lines and covers one cohesive domain; split into auxiliary files like REFERENCE.md or EXAMPLES.md when exceeding that limit or spanning distinct subject areas.

The mattpocock/skills repository establishes strict conventions for organizing agent capabilities to optimize AI parsing performance. Understanding when to split a skill into multiple files vs keeping in SKILL.md directly impacts how effectively agents identify trigger conditions and execute workflows.

The 100-Line Threshold in write-a-skill/SKILL.md

According to the canonical guidelines in write-a-skill/SKILL.md (lines 100-107), file length serves as the primary splitting criterion. When your SKILL.md exceeds 100 lines, the documentation becomes unwieldy for agents attempting to quickly parse triggering conditions and core functionality.

Maintaining a concise central file allows the agent to rapidly determine what the skill does and when to invoke it. Move the bulk of detailed documentation to auxiliary files to preserve this readability and prevent context window bloat.

Why Agent Context Windows Matter

AI agents have limited context when evaluating which skills to activate. A bloated SKILL.md forces the agent to process irrelevant details before identifying trigger conditions, potentially causing missed invocations or latency. Keeping the core description under 100 lines ensures the essential metadata—including the description frontmatter field—remains immediately accessible for matching against user queries.

Domain Separation Strategy

Beyond line count, content domains dictate file organization. When your skill documentation naturally falls into distinct subject areas—such as separate schemas for finance versus sales, or invoice processing versus payroll processing—splitting into multiple files improves maintainability.

According to the repository guidelines, each domain should reside in its own logical file (e.g., REFERENCE.md for data models, EXAMPLES.md for usage patterns), with the main SKILL.md serving as a curated index linking to these deep-dive resources.

Handling Advanced or Rarely-Used Features

Place rarely-accessed sections—deep technical specifications, optional configuration scripts, or edge-case workflows—into separate files. This keeps the main SKILL.md focused on common use cases while preserving detailed documentation for power users who need it. The write-a-skill/scripts/ directory can house deterministic utility scripts that are bundled only when necessary.

Code Examples: Single File vs. Multi-File Structures

Single-File Skill: Under 100 Lines

When your skill is straightforward and compact, consolidate everything into SKILL.md:

---
name: simple-pdf-extractor
description: Extract text and tables from PDFs. Use when a user mentions PDFs, tables, or document extraction.
---

# Simple PDF Extractor

## Quick start

`pdf-extract <input.pdf>`

## Workflows

1. Upload PDF.
2. Run `pdf-extract`.
3. Retrieve extracted text.

## Advanced features

See [REFERENCE.md](REFERENCE.md) for optional OCR settings.

This example demonstrates the single-file pattern where all essential information lives inside SKILL.md because the skill remains concise and cohesive.

Multi-File Skill: Over 100 Lines or Multiple Domains

For complex skills exceeding the line limit or spanning distinct domains, distribute content across specialized files:

SKILL.md (core trigger definition, under 100 lines):

---
name: finance-suite
description: Perform finance-related data transformations. Use when a user mentions invoices, payments, or accounting.
---

# Finance Suite

## Quick start

`finance-transform <csv>`

## Workflows

- Load CSV → Transform → Export JSON.

## Detailed docs

- [REFERENCE.md](REFERENCE.md) – data model definitions, schema versions.
- [EXAMPLES.md](EXAMPLES.md) – sample pipelines for invoices vs. payroll.

REFERENCE.md (detailed domain documentation):

# Finance Suite – Reference

## Invoice Schema

- Fields: id, amount, due_date, status ...

## Payroll Schema

- Fields: employee_id, salary, period ...

*Each schema lives in its own logical section because they belong to distinct finance sub-domains.*

EXAMPLES.md (concrete usage patterns):

# Finance Suite – Examples

## Invoice processing

```sh
finance-transform invoices.csv --schema invoice > invoices.json

Payroll processing

finance-transform payroll.csv --schema payroll > payroll.json

*By delegating heavy documentation to REFERENCE.md and EXAMPLES.md, the main SKILL.md stays compact, satisfying the under-100-lines rule while providing exhaustive auxiliary information for specific domains.*

## Summary

- **Keep it single**: Maintain one [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) when content stays under 100 lines and covers a unified topic, ensuring rapid agent parsing.
- **Split by size**: Move documentation bulk to auxiliary files when exceeding the 100-line threshold defined in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 100-107).
- **Split by domain**: Create separate files for distinct subject areas (e.g., finance vs. sales schemas) to improve modularity and contributor safety.
- **Link strategically**: Use the main SKILL.md as an index linking to REFERENCE.md, EXAMPLES.md, or domain-specific files.
- **Preserve performance**: Concise core files prevent context window bloat and improve agent trigger accuracy.

## Frequently Asked Questions

### What is the maximum recommended length for a SKILL.md file?

The `mattpocock/skills` repository specifies **100 lines** as the practical maximum for a SKILL.md file according to lines 100-107 in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md). Beyond this limit, agents struggle to quickly identify trigger conditions, and contributors face increased risk of merge conflicts when editing dense documentation.

### Should I split my skill if it covers multiple domains?

Yes. When content spans distinct domains—such as separate data schemas for invoices versus payroll, or different API versions—create individual files for each domain. The main SKILL.md should contain only the core description and links to these auxiliary files, following the modular documentation pattern established in the repository.

### How do I link auxiliary files to the main SKILL.md?

Reference auxiliary files using standard Markdown links within your SKILL.md, typically in a "Detailed docs" or "See also" section. For example, include `- [REFERENCE.md](REFERENCE.md) – technical specifications` to guide both agents and human contributors toward extended documentation without cluttering the primary trigger definition.

### What auxiliary filenames does the repository recommend?

The canonical structure uses **REFERENCE.md** for deep technical details and data model definitions, **EXAMPLES.md** for concrete usage snippets and workflow demonstrations, and optionally **scripts/** directories for deterministic utilities. These filenames appear consistently throughout `mattpocock/skills` and integrate deterministically with the skill-authoring toolchain.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}