Skills

Load detailed instructions on demand to keep prompts lightweight

Prompts get unwieldy when you pack every instruction into the system message. Skills solve this. They are lazy-loaded instruction packages that keep your initial context window small while providing deep expertise on demand.

How Skills Work

Skills are markdown documents with a name, description, and body of instructions. At prompt render time, Output builds a summary of available skills and adds it to the system message:

The LLM decides which skills are relevant for the task and loads them when nessesary.

Providing Skills

There are three ways to give skills to an LLM call in Output: colocated files, frontmatter paths, or inline code.

Colocated Files (Auto-Discovery)

Place .md files in a skills/ folder next to your prompt file. Output discovers them automatically, no configuration needed.

prompts/
├── [e-mail]
└── skills/
    ├── clarity_guidelines.md
    ├── response_format.md
    └── structure_guide.md

Each skill file is markdown with optional YAML frontmatter for name and description:

clarity_guidelines.md

---
name: clarity_guidelines
description: Rules for writing clear, readable technical content
---

# Clarity Guidelines

When reviewing or writing technical content for clarity:

1. **Sentence length**: Keep sentences under 25 words when possible.
   Break complex ideas into multiple sentences.

2. **Active voice**: Prefer active voice ("The function returns X")
   over passive ("X is returned by the function").

3. **Jargon**: Define technical terms on first use.
   Avoid unnecessary acronyms without explanation.

4. **Concrete examples**: Every abstract concept should have
   a concrete example.

When applying this skill, flag any violations you find
and suggest improvements.

The prompt file itself doesn’t need any special configuration. The skills directory is discovered by convention:

[e-mail]

---
provider: anthropic
model: claude-sonnet-4-20250514
maxTokens: 2048
---

<system>
You are an expert technical writing assistant.
Use load_skill to get the full instructions for any skill before applying it.
</system>

<user>
Review the following {{ content_type }} content focusing on {{ focus }}.

Content:
{{ content }}
</user>

Frontmatter Paths (Explicit)

For explicit control over which skills are loaded, list paths in the prompt frontmatter. Paths can point to individual files or directories of .md files, resolved relative to the prompt file’s location:

[e-mail]

---
provider: anthropic
model: claude-sonnet-4-20250514
skills:
  - ./skills/
  - ../shared_skills/tone_guide.md
---

<system>
You are an expert technical writing assistant.
</system>

<user>
Review {{ content }}.
</user>

When skills: is set in frontmatter, auto-discovery of the colocated skills/ directory is skipped. Only the explicitly listed paths are loaded.

Inline Skills (Code)

Create skills programmatically with the skill() function. This is useful when skill content is dynamic or generated from data:

steps.ts

import { skill } from '@outputai/llm';

const audienceSkill = skill({
  name: 'audience_adaptation',
  description: 'Tailor feedback for the specified expertise level',
  instructions: `# Audience Adaptation

When the target audience is specified, adjust your feedback:

**Beginner audience**: Flag jargon and unexplained concepts as
high-priority issues. Prioritize clarity over conciseness.

**Expert audience**: Focus on accuracy, completeness, and advanced
concerns. Basic explanations are unnecessary.

Always mention the audience level in your summary.`
});

Pass inline skills to generateText or Agent:

import { generateText } from '@outputai/llm';

const { result } = await generateText({
  prompt: 'writing_assistant@v1',
  variables: { content_type: 'documentation', focus: 'clarity', content: input.content },
  skills: [audienceSkill],
  maxSteps: 5
});

import { Agent } from '@outputai/llm';

const agent = new Agent({
  prompt: 'writing_assistant@v1',
  variables: { content_type: 'documentation', focus: 'clarity', content: input.content },
  skills: [audienceSkill],
  maxSteps: 5
});
const { text } = await agent.generate();

Inline skills are merged with any file-based skills (from auto-discovery or frontmatter paths).

Skill File Format

Skill files are markdown documents with an optional YAML frontmatter block:

Field	Required	Default	Description
name	No	Filename without .md	Identifier the LLM uses with load_skill
description	No	Same as name	When to use this skill (shown in system message)
Body	Yes	-	Full instructions returned by load_skill

If you omit the frontmatter entirely, the filename (without .md) is used as both the name and description. A file named clarity_guidelines.md with no frontmatter would have name: "clarity_guidelines" and description: "clarity_guidelines".

Write good descriptions. They’re what the LLM uses to decide whether to load a skill. “Rules for writing clear, readable technical content” is better than “clarity_guidelines”.

Resolution Priority

Skills are resolved in this order:

1. Frontmatter paths: If skills: is set in the prompt frontmatter, those paths are loaded
2. Colocated auto-discovery: If no skills: in frontmatter, the skills/ directory next to the prompt file is scanned
3. Caller-provided skills: Skills passed via code (skills: [...] in generateText or Agent) are always merged in

Frontmatter paths and colocated auto-discovery are mutually exclusive. Setting skills: in frontmatter disables auto-discovery. Caller-provided skills are always added regardless of which file-based method is used.

Disabling Skills

Set skills: [] in the prompt frontmatter to explicitly opt out of auto-discovery:

[e-mail]

---
provider: anthropic
model: claude-haiku-4-5-20251001
maxTokens: 2048
skills: []
---

<system>
You are an expert technical writing assistant.
</system>

<user>
Review the following {{ content_type }} content focusing on {{ focus }}.

Content:
{{ content }}
</user>

This is useful when you have a skills/ directory for other prompts in the same folder, but a specific prompt should not load any skills.