/output-dev-skill-file

name: output-dev-skill-file
description: Create .md skill files for Output framework's lazy-loaded instruction system. Use when adding skills to prompts, configuring skill loading, or debugging skill resolution.
allowed-tools: [Read, Write, Edit]

Creating Skill Files

Overview

This skill documents how to create `.md` skill files for the Output framework's skills system. Skills are lazy-loaded instruction packages that keep prompts lightweight. The LLM sees a list of skill names and descriptions in the system message, then calls a `load_skill` tool to retrieve full instructions on demand.

**Important**: These are framework skills (`.md` files loaded by LLMs at runtime), not Claude Code plugin skills. The naming is similar but the systems are separate.

When to Use This Skill

• Adding reusable instruction sets to LLM prompts
• Configuring how skills are loaded (auto-discovery, frontmatter, inline)
• Debugging skill resolution or `load_skill` tool issues
• Organizing shared expertise across multiple prompts

Location Convention

Skill files live in a `skills/` folder next to the prompt file. Output auto-discovers them with no configuration needed:

src/workflows/{workflow-name}/
├── workflow.ts
├── steps.ts
├── types.ts
└── prompts/
    ├── writing_assistant@v1.prompt
    └── skills/
        ├── clarity_guidelines.md
        ├── response_format.md
        └── structure_guide.md

The `skills/` folder is relative to the prompt file location, not the workflow root.

Skill File Format

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

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

Frontmatter Fields

| Field | Required | Default | Description | |-------|----------|---------|-------------| | `name` | No | Filename without `.md` | Identifier the LLM uses with `load_skill` | | `description` | No | Same as `name` | Shown in system message, helps LLM decide when to load | | Body | Yes | - | Full instructions returned when LLM calls `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 gets `name: "clarity_guidelines"` and `description: "clarity_guidelines"`.

Write good descriptions. They appear in the system message and are what the LLM uses to decide whether to load a skill. "Rules for writing clear, readable technical content" is better than "clarity_guidelines".

How Skills Are Loaded

Method 1: Colocated Auto-Discovery (Default)

Place `.md` files in a `skills/` folder next to your prompt file. Output discovers them automatically. The prompt file needs no special configuration. (Model lines below are current as of 2026-05-04 — refresh via [`output-dev-model-selection`](../output-dev-model-selection/SKILL.md).)

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

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

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

Content:
{{ content }}
</user>

At runtime, Output finds the colocated `skills/` directory, loads all `.md` files, and: 1. Adds a summary of available skills to the system message 2. Injects a `load_skill` tool the LLM can call

Method 2: Frontmatter Paths (Explicit)

Reference specific skill files or directories in the prompt YAML frontmatter. Paths resolve relative to the prompt file:

---
provider: anthropic
# current as of 2026-05-04 — run output-dev-model-selection for the latest
model: claude-sonnet-4-6
skills:
  - ./skills/
  - ../shared_skills/tone_guide.md
---

When `skills:` is set in frontmatter, auto-discovery is skipped. Only the listed paths are loaded.

Method 3: Inline Skills (Code)

Create skills programmatically with the `skill()` function from `@outputai/llm`:

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**: Flag jargon as high-priority issues.
**Expert**: Focus on accuracy and completeness.

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

Pass inline skills to `generateText` or `Agent`:

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

Inline skills are merged with any file-based skills.

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