Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
The problem

A skill that starts as 50 lines of markdown tends to grow. You add edge cases, new workflows, reference tables. Before long it’s 800 lines and the agent loads it all into context every time — even when only one workflow is needed. The agent skills spec recommends keeping SKILL.md under 500 lines. But real-world skills often need more than that. The solution is structure.

​
The router pattern

Instead of putting every instruction in SKILL.md, use it as a router — a compact entry point that identifies which workflow the user needs and loads only that workflow’s instructions. 
my-skill/
├── SKILL.md              # ~100-200 lines: frontmatter + router
├── workflows/
│   ├── create.md         # Workflow: creating from scratch
│   ├── edit.md           # Workflow: modifying existing work
│   ├── analyze.md        # Workflow: analysis and reporting
│   └── export.md         # Workflow: exporting to other formats
├── scripts/
│   └── validate.sh       # Deterministic validation
└── references/
    └── schema.md         # Data model reference
The SKILL.md contains:
  1. Frontmatter — name, description, trigger keywords
  2. Router table — maps user intent to a workflow file
  3. Shared context — only what every workflow needs (e.g., data model basics)
---
name: my-skill
description: Build and analyze financial models. USE WHEN model, forecast, ...
---

# My Skill

## Workflow routing

Based on the user's request, read the appropriate workflow file:

| User intent | Workflow file |
|-------------|--------------|
| Create a new model | `workflows/create.md` |
| Edit or update an existing model | `workflows/edit.md` |
| Analyze or review a model | `workflows/analyze.md` |
| Export to another format | `workflows/export.md` |

Read the workflow file before proceeding. Do not attempt the task from memory.

## Shared context

[Only the minimum context every workflow needs — maybe 20-30 lines]
This keeps the initial context load small. The agent reads ~200 lines to understand the skill, then loads only the ~100-200 lines of the specific workflow it needs.

​
When to split into workflows

Split when you notice:
  • Distinct entry points — users arrive with different intents (create vs. edit vs. analyze)
  • Non-overlapping instructions — the steps for one workflow don’t apply to another
  • Growing SKILL.md — you’re past 300 lines and still adding
Don’t split when:
  • All instructions apply to every invocation
  • The skill is genuinely simple (under 200 lines)
  • Splitting would create workflows with only 20 lines each

​
Scripts vs. inline instructions

A common question: should the logic live as markdown instructions or as a script? Use markdown instructions when the agent needs judgment — choosing between approaches, adapting to context, interpreting ambiguous input. Use scripts when the logic is deterministic — validation, data transformation, formatting. Scripts are faster, cheaper (no tokens), and more reliable for repeatable operations. 
# Good split:
# - SKILL.md tells the agent WHEN and WHY to validate
# - scripts/validate.sh does the actual validation deterministically
A useful heuristic from the agent skills spec: if you find the agent reinventing the same logic every run, bundle it as a tested script.

​
CLI error steering

A powerful technique for keeping skills lean: instead of documenting every possible error path in SKILL.md, let your CLI or scripts return actionable error messages that steer the agent. 
# Instead of documenting "if step 2 fails, do X" in SKILL.md:
Error: Schema validation failed.
Run: my-tool fix-schema --input data.json
Then retry: my-tool build --input data.json
The agent reads the error output and follows the instructions. This moves error handling out of the context window and into deterministic code — where it’s more reliable anyway.

​
References vs. workflows

TypePurposeWhen to load
WorkflowStep-by-step instructions for a specific taskWhen the router selects it
ReferenceLookup tables, schemas, specsOnly when a workflow says to
Keep references separate so they’re loaded only when needed: 
# In workflows/create.md:
## Step 3: Define the schema

Read `references/schema.md` for the full field reference.

​
Nesting skills vs. composing them

The agent skills spec treats each skill as an independent unit. If you have two related capabilities, you have two options: One skill with multiple workflows — use when the capabilities share context, data models, or are always used together. Separate skills — use when the capabilities are independently useful and don’t share state. Don’t create “meta-skills” that orchestrate other skills unless you have a concrete need. The agent is already good at routing between independent skills.

​
Next steps

Managing Context

Keep your skill’s context footprint small.

Testing Triggers

Verify your skill fires when it should.