/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
• Listing skill paths in prompt frontmatter
• 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. List that folder (or individual files) in the prompt frontmatter. A sibling `skills/` directory is not loaded unless the prompt names it:

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

List skill paths in the prompt YAML frontmatter. Paths resolve relative to the prompt file and can be individual `.md` files or directories of `.md` files. (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
maxOutputTokens: 2048
skills:
  - ./skills
  - ../shared_skills/tone_guide.md
---

<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 loads the listed paths and: 1. Adds a summary of available skills to the system message 2. Injects a `load_skill` tool the LLM can call

List skill paths in the prompt frontmatter.

Omit `skills` (or set `skills: []`) when a prompt should load none. A sibling `skills/` folder used by other prompts in the same directory is not inherited.

Complete Example

Skill File

---
name: response_format
description: Standard format requirements for all review responses
---

# Response Format

Every response MUST end with the exact string "OUTPUT_COMPLETE" on its own line.

Structure your review as follows:

1. **Summary**: 2-3 sentence overview of the content quality
2. **Issues**: Numbered list of specific problems found
3. **Suggestions**: Actionable improvements for each issue
4. **Score**: Overall quality score from 0-100

OUTPUT_COMPLETE

Prompt File Using Skills

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

<system>
You are an expert technical writing assistant.
Use load_skill to get the full instructions for any skill before applying it.
After reviewing, provide structured feedback with specific issues and suggestions.
</system>

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

Content:
{{ content }}
</user>

Step Using the Prompt

import { step, z } from '@outputai/core';
import { Agent, aiSdk } from '@outputai/llm';

export const reviewContent = step( {
  name: 'reviewContent',
  description: 'Review content using skills for specialized expertise',
  inputSchema: z.object( {
    content: z.string(),
    content_type: z.string(),
    focus: z.string()
  } ),
  outputSchema: z.object( {
    summary: z.string(),
    issues: z.array( z.string() ),
    suggestions: z.array( z.string() ),
    score: z.number()
  } ),
  fn: async input => {
    const agent = new Agent( {
      prompt: 'writing_assistant@v1',
      variables: inpu