Supporting Files
A skill file contains the instructions the agent follows. But many real-world skills need more than instructions â they need templates, scripts, example files, configuration snippets, or reference documentation. These supporting files live alongside the SKILL.md in the skill's directory and are loaded on demand (Tier 3) when the skill instructs the agent to read them.
Skill Directory Structure
Every skill lives inside a named directory. The only required file is SKILL.md. Everything else is optional supporting content.
In this example, the new-endpoint skill has three templates, two reference examples, and a conventions document. None of these are loaded until the skill instructions tell the agent to read them.
Referencing Files with ${SKILL_DIR}
The ${SKILL_DIR} variable resolves to the absolute path of the skill's directory. This is the primary mechanism for referencing supporting files in a portable way.
---
description: Create a new API endpoint with route, tests, and schema
allowed-tools:
- Read
- Write
- Bash(npm test -- --filter $1)
---
# New API Endpoint: $1
## Step 1: Read templates
Read the following template files:
- Route template: ${SKILL_DIR}/templates/route.ts.hbs
- Test template: ${SKILL_DIR}/templates/route.test.ts.hbs
- Schema template: ${SKILL_DIR}/templates/schema.ts.hbs
## Step 2: Read reference examples
Look at these working examples to understand the patterns:
- ${SKILL_DIR}/examples/get-users.ts
- ${SKILL_DIR}/examples/create-order.ts
## Step 3: Read conventions
Read ${SKILL_DIR}/conventions.md for naming and style rules.
## Step 4: Generate files
Use the templates and conventions to create:
1. src/routes/$1.ts
2. src/routes/$1.test.ts
3. src/schemas/$1.schema.ts
## Step 5: Verify
Run `npm test -- --filter $1` to confirm the new endpoint works.You could paste template content directly into the SKILL.md body, but there are strong reasons not to. Supporting files keep the skill body concise and readable. They enable Tier 3 progressive disclosure, so templates only consume context tokens when actually needed. And they can be edited independently without touching the skill instructions.
Types of Supporting Files
Templates
Templates are the most common supporting file. They provide the structure that the agent fills in with project-specific content.
import { Router } from "express";
import { z } from "zod";
import { validate } from "../middleware/validate";
import { {{schemaName}} } from "../schemas/{{name}}.schema";
const router = Router();
/**
* {{method}} /api/{{name}}
* {{description}}
*/
router.{{method}}("/", validate({{schemaName}}), async (req, res) => {
try {
// TODO: Implement handler
res.json({ success: true });
} catch (error) {
res.status(500).json({ error: "Internal server error" });
}
});
export default router;The double-brace placeholders are not a special agent feature â they are just markers that the agent knows to replace. You can use any placeholder style you like. Agents are smart enough to understand the intent from the skill instructions.
Reference Documentation
Include Markdown files with project conventions, API documentation, or coding standards that the skill should follow.
# API Endpoint Conventions
## Naming
- Route files: kebab-case (e.g., get-users.ts)
- Schema files: kebab-case with .schema suffix
- Test files: same name with .test suffix
## Error Handling
- Always use the AppError class from src/errors
- Never expose internal error messages to clients
- Log all 5xx errors with the structured logger
## Validation
- All input must be validated with Zod schemas
- Schemas live in src/schemas/
- Use the validate middleware, never validate inline
## Response Format
- Success: { data: T, meta?: { page, total } }
- Error: { error: { code: string, message: string } }Helper Scripts
Supporting files can include shell scripts that the skill instructs the agent to execute. This is useful for multi-step operations that are easier to express as a script.
---
description: Deploy with preflight checks and rollback capability
allowed-tools:
- Read
- Bash(${SKILL_DIR}/scripts/preflight-check.sh)
- Bash(${SKILL_DIR}/scripts/rollback.sh)
- Bash(git *)
- Bash(docker compose *)
---
# Deployment
## Step 1: Preflight
Run the preflight check script:
`${SKILL_DIR}/scripts/preflight-check.sh`
If it fails, stop and report the issues.
## Step 2: Deploy
Read the deployment config from ${SKILL_DIR}/config.json
and proceed with the deployment.
## Step 3: Verify
If deployment fails, run the rollback script:
`${SKILL_DIR}/scripts/rollback.sh`Notice how the allowed-tools field restricts Bash to only the specific scripts in the skill's directory. This ensures the skill can run its own scripts but cannot execute arbitrary commands beyond what is explicitly permitted.
Working Examples
Including example files gives the agent concrete references of what good output looks like. This is often more effective than trying to describe the desired format in prose.
---
description: Write a migration file following project patterns
allowed-tools:
- Read
- Write
---
Read the example migration to understand the expected format:
${SKILL_DIR}/examples/001-create-users.ts
Now create a new migration for: $ARGUMENTS
Follow the exact same structure, naming convention,
and error handling patterns shown in the example.Conditional File Loading
Skills with multiple supporting files should not always load all of them. Write instructions that tell the agent to load only what is relevant.
---
description: Generate a new page for the application
allowed-tools:
- Read
- Write
- Glob
---
# New Page Generator
Ask the user what type of page they need, then load the
appropriate template:
- **Static page** â Read ${SKILL_DIR}/templates/static-page.tsx
- **Dynamic page with data fetching** â Read ${SKILL_DIR}/templates/dynamic-page.tsx
- **Dashboard page with charts** â Read ${SKILL_DIR}/templates/dashboard-page.tsx
- **Form page** â Read ${SKILL_DIR}/templates/form-page.tsx
Only load the ONE template that matches. Do not load all four.
After reading the template, also read:
${SKILL_DIR}/conventions.md (always required)Organizing Large Skills
For complex skills with many supporting files, use a clear folder structure:
If a skill's directory is growing beyond 10-15 supporting files, consider whether you are trying to do too much in a single skill. Breaking a complex workflow into multiple smaller skills often produces better results, because each skill's instructions stay focused and the context window is not overloaded.
Supporting Files and Version Control
Supporting files should be committed to version control alongside the SKILL.md. This ensures that:
- Every team member has the same templates and reference files.
- Changes to templates are tracked, reviewed, and can be rolled back.
- The skill and its supporting files stay in sync â a template change that requires an instruction change happens in the same commit.
What's Next
You now have a complete picture of the intermediate skill system: progressive disclosure, string substitutions, dynamic context, tool restrictions, and supporting files. The next section dives into advanced patterns â subagent execution, hooks integration, and meta-skills that generate other skills.