A SKILL.md file on its own teaches an agent a workflow. Supporting files make that workflow significantly better. Reference documents give the agent detailed context it can look up. Scripts automate repetitive steps. Examples show the agent what good output looks like. Here's how to build each one.

What are supporting files?

A skill folder can contain more than just a SKILL.md. The typical structure looks like this: code-reviewer/ ├── SKILL.md ├── references/ │ ├── owasp-top-10.md │ └── code-smells.md ├── scripts/ │ └── count-coverage.sh └── examples/ ├── input-sample.py └── expected-output.md The agent reads the SKILL.md for instructions and can reference the supporting files when the instructions tell it to. For example, the SKILL.md might say "Check the code against the patterns listed in references/owasp-top-10.md."

Why Supporting Files Matter

Supporting files elevate your skill from a mere set of instructions to a powerful, reliable tool. They help agents perform tasks more accurately, save time, and reduce errors. According to Agensi marketplace data, skills with comprehensive supporting files sell for 2-3x more than those with just the SKILL.md because buyers see the added value and usability.

How to Organize Your Skill Folder

Start by structuring your skill folder clearly: 1. Create a `references/` directory for documents that provide in-depth background, checklists, or specifications. 2. Add a `scripts/` folder to include helper scripts automating repetitive or complex tasks. 3. Use an `examples/` folder to showcase sample inputs and expected outputs, demonstrating how the skill should function. This organization helps both agents and users navigate your skill with ease.

Writing Reference Files: Detailed Context for Your Agent

Reference files help agents understand the nuanced details of your domain or workflow. These files can be markdown documents, PDFs, or text files that contain guidelines, best practices, or patterns to follow. Practical example: If you are building a skill for code review, your reference file might list common code smells or security vulnerabilities like the OWASP Top 10. This document serves as a checklist the agent refers to during analysis. Steps to create effective reference files: 1. Identify critical concepts or standards relevant to the skill. 2. Summarize these clearly and concisely. 3. Format the document for easy reading, using headings, bullet points, and tables. 4. Link the reference file in your SKILL.md to enable the agent to pull information as needed. Tip: Keep your references updated as standards evolve to maintain skill accuracy.

Crafting Helper Scripts: Automate and Simplify

Scripts are powerful tools that automate parts of your workflow, making your skill faster and less error-prone. They can be shell scripts, Python scripts, or any executable code relevant to the task. Example use case: In a skill that audits code coverage, include a script like `count-coverage.sh` that runs coverage reports and outputs a summary the agent can parse. How to write useful helper scripts: 1. Identify repetitive or complex steps in the workflow. 2. Write scripts that take input parameters and produce clear, structured output. 3. Test scripts independently to ensure reliability. 4. Document script usage within SKILL.md or a README. Tip: Design scripts to be idempotent so they can be run multiple times without side effects.

Creating Examples: Show, Don’t Just Tell

Examples are the proof of your skill’s capability. They demonstrate exactly what input looks like and what output the agent should generate. This clarity helps buyers understand the skill’s value and helps agents produce consistent results. Real-world example: For a data cleaning skill, provide sample raw data files in `examples/input-data.csv` and the cleaned, processed data in `examples/cleaned-output.csv`. Steps to build effective examples: 1. Collect typical inputs the agent will encounter. 2. Run your skill manually or via scripts to generate expected outputs. 3. Store both input and output files with clear, descriptive names. 4. Reference these examples in your SKILL.md so the agent knows when and how to use them. Tip: Include edge case examples to improve the agent’s robustness.

Integrating Supporting Files into SKILL.md

Your SKILL.md should explicitly reference supporting files to unlock their value. For example, instructions might say: - "Refer to `references/code-smells.md` for patterns to detect." - "Run the `scripts/count-coverage.sh` script to generate coverage data." - "Compare your output against `examples/expected-output.md` to ensure accuracy." Clear integration guides the agent through the workflow, combining textual instructions with actionable resources.

Tips for Maximizing Skill Value

1. Keep file names descriptive and consistent – This makes navigation intuitive. 2. Use markdown format for references – Markdown is easy to parse and read. 3. Test your scripts across environments – Ensure compatibility. 4. Version control your skill folder – Track changes and improvements. 5. Document everything clearly – Both for users and agents. These practices make your skill professional and trustworthy, increasing buyer confidence.

Real-World Use Cases

- Security Auditing Skill: Uses `references/owasp-top-10.md` for vulnerability definitions, `scripts/scan-vulns.sh` to automate scanning, and `examples/scan-report.md` showing a sample vulnerability report. - Content Moderation Skill: Contains reference guidelines on prohibited content, scripts to flag texts automatically, and examples of flagged versus clean content. - Financial Modeling Skill: Includes references to accounting standards, scripts that run calculations, and example spreadsheets to demonstrate output. Each use case shows how supporting files turn a basic instruction set into a powerful, sellable skill.

Conclusion

Creating supporting files for your SKILL.md is not just a best practice—it’s a game-changer. By providing references, scripts, and examples, you increase your skill’s clarity, reliability, and market value. Follow the structured approach outlined here to build compelling supporting files that make your skills stand out in the marketplace and deliver real value to users.