Advanced AI Agent Skill Patterns — Multi-File, Sub-Agents and Composition

Once you have built a few basic skills, the next level is production-grade patterns: multi-file skills with progressive loading, sub-agents for focused tasks, composable skills that work together. These are what separates hobby skills from professional ones.

The basic SKILL.md pattern handles an enormous range of useful capabilities. But as you build more skills and tackle more complex use cases, you will encounter situations where the simple pattern is not enough. Production-grade skills use several advanced patterns that solve specific problems.

Multi-File Skills with Progressive Loading

Large skills with extensive documentation should split content across multiple files, with SKILL.md acting as the index. The agent loads SKILL.md when triggered, then loads other files only when SKILL.md explicitly references them.

A typical structure for a complex skill:

complex-skill/
├── SKILL.md              # always loaded when triggered
├── REFERENCE.md          # loaded on demand
├── EXAMPLES.md           # loaded on demand
├── TROUBLESHOOTING.md    # loaded on demand
└── scripts/
    └── main.py

In SKILL.md, reference other files by name when the agent should read them: "For detailed error code mappings, read REFERENCE.md." The agent knows to load that file when it encounters error codes. This keeps the main skill body focused while preserving rich reference content for the cases that need it.

Skills with Sub-Agents

Advanced agents like Claude Code support sub-agents — separate agent instances spawned to handle specific specialised tasks. Skills can launch sub-agents for work that benefits from focused context.

The most useful pattern: a skill that needs to perform a long research task. Rather than cluttering the main conversation with intermediate results, the skill spawns a sub-agent with the research goal and a limited toolset, lets it work for several minutes, and returns only the final result to the main conversation. The main agent context stays clean. The sub-agent operates with full focus.

Composable Skills That Work Together

Skills compose naturally because the agent can invoke multiple skills in sequence. A request like "research this company and prepare a presentation about them" might activate three skills: web-research, content-synthesiser and pptx. Each handles its phase, and the agent orchestrates the sequence automatically.

When building skills you expect to compose, make outputs and inputs predictable. A research skill that produces structured JSON is more useful than one that produces flowing prose, because subsequent skills can parse the JSON reliably. Document expected output formats in your SKILL.md so composition works smoothly.

Skills with FORMS.md for Structured Input

FORMS.md is a convention for skills that need to collect structured information from the user. A skill helping fill out a job application form might have a FORMS.md listing every field the application requires. The SKILL.md says: "Before generating the cover letter, ensure you have collected all required information. Refer to FORMS.md for the complete list of fields and ask the user for any missing values."

Versioning and Semantic Updates

Skills are software and benefit from semantic versioning in the version field: 1.0.0 → 1.1.0 for new capabilities, 1.0.0 → 2.0.0 for breaking changes that require users to adapt. Maintain a CHANGELOG.md if you publish updates. The skills.sh marketplace surfaces version information so users can decide when to upgrade.