How to Write SKILL.md Supporting Files: References, Scripts, and Examples

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.

Quick Answer: Supporting files go inside your skill folder alongside SKILL.md. Use references/ for context documents the agent can read (checklists, patterns, specs), scripts/ for helper scripts the agent can execute, and examples/ for sample inputs and outputs. Skills with supporting files sell for 2-3x more on Agensi because they deliver more value.

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."

How do I write reference files?

Reference files are markdown documents containing information the agent should consult during execution. They work like a knowledge base that the agent reads on demand.

Checklists. A security audit skill might include references/owasp-top-10.md with each vulnerability category, what to look for, and example patterns. The SKILL.md instruction says "For each OWASP category listed in references/owasp-top-10.md, check whether the code contains any matching patterns."

Pattern libraries. A code review skill might include references/code-smells.md with common anti-patterns. "Check the code against each pattern in references/code-smells.md and report any matches."

Style guides. A frontend skill might include references/design-tokens.md with color scales, spacing values, and typography rules. The agent uses these as constraints when generating components.

Specifications. A data validation skill might include references/schema.md with the expected data format. The agent validates inputs against this spec.

Keep reference files focused and well-structured with clear headings. The agent reads them as context, so the clearer the structure, the better it follows the content.

How do I write helper scripts?

Scripts automate steps that are easier to do programmatically than through natural language instructions. The SKILL.md tells the agent when and how to run them.

Keep scripts simple and safe. They should operate only within the current project directory, not require elevated permissions or root access, not install packages globally, not delete files outside the project, and not make network requests unless essential and documented.

Make scripts executable. Include a shebang line (#!/bin/bash or #!/usr/bin/env python3) and note in the SKILL.md that the agent should run chmod +x scripts/your-script.sh if needed.

Document what scripts do. Add comments at the top of each script explaining its purpose, inputs, and outputs. This helps the security scan pass and builds buyer trust.

Example script for a testing skill (scripts/find-untested.sh):

#!/bin/bash
# Finds source files with no corresponding test file
# Usage: ./scripts/find-untested.sh src/

find "$1" -name "*.ts" -not -name "*.test.ts" | while read src; do
  test_file="${src%.ts}.test.ts"
  if [ ! -f "$test_file" ]; then
    echo "UNTESTED: $src"
  fi
done

The SKILL.md would reference this: "Run scripts/find-untested.sh on the source directory to identify files without test coverage, then generate tests for each untested file."

How do I write example files?

Examples show the agent what good output looks like. They're the most underutilized supporting file type and they significantly improve output quality.

Input examples. A sample file that represents typical input the skill would process. For a code review skill, include a small code file with intentional issues. For a testing skill, include a function that should be tested.

Output examples. The expected output when the skill processes the input. This is a powerful technique because the agent uses it as a template for formatting and structure. If your output example groups findings by severity and includes line references, the agent will follow that pattern.

Before/after examples. For skills that transform code (refactoring, migration, formatting), include a before file and an after file showing the expected transformation.

In your SKILL.md, reference the examples: "Format your output following the pattern shown in examples/expected-output.md."

How do supporting files affect pricing?

Skills with supporting files consistently sell for more on Agensi. A bare SKILL.md with instructions is worth $3 to $5. A skill with references, scripts, and examples is worth $12 to $25 because the buyer gets a complete solution rather than just instructions.

The supporting files represent work you've already done that the buyer would otherwise have to do themselves. That work has clear value and justifies a higher price.

For pricing guidance, read How to Price Your SKILL.md Skills.

---

Build comprehensive skills and sell them on Agensi. You keep 80% of every sale.