> ## Documentation Index
> Fetch the complete documentation index at: https://docs.output.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/
├── writing_assistant@v1.prompt
└── skills/
    ├── clarity_guidelines.md
    ├── response_format.md
    └── structure_guide.md
```

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

```markdown clarity_guidelines.md theme={null}
---
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:

```yaml writing_assistant@v1.prompt theme={null}
---
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:

```yaml writing_assistant@v1.prompt theme={null}
---
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:

```typescript steps.ts theme={null}
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`:

```typescript theme={null}
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
});
```

```typescript theme={null}
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

<Note>
  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.
</Note>

## Disabling Skills

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

```yaml no_skills_assistant@v1.prompt theme={null}
---
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>
```

<Tip>
  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.
</Tip>