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

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

---
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: input,
      output: aiSdk.Output.object( {
        schema: z.object( {
          summary: z.string().describe( '2-3 sentence overview' ),
          issues: z.array( z.string() ).describe( 'Specific problems found' ),
          suggestions: z.array( z.string() ).describe( 'Actionable improvements' ),
          score: z.number().describe( 'Quality score 0-100' )
        } )
      } )
    } );
    const { output } = await agent.generate();
    return output;
  }
} );

Best Practices

1. Write Focused Skills

Each skill should cover one area of expertise. Prefer multiple focused skills over one large skill:

skills/
├── clarity_guidelines.md      # Writing clarity
├── structure_guide.md         # Document structure
└── response_format.md         # Output formatting

2. Write Descriptive Descriptions

The description appears in the system message. Make it clear when the LLM should load this skill:

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

Not:

---
name: clarity_guidelines
description: clarity_guidelines
---

3. Structure Instructions with Headers

Use markdown headers and lists for scannable instructions:

# Clarity Guidelines

## Rules
1. Keep sentences under 25 words
2. Prefer active voice
3. Define jargon on first use

## When to Flag
- Sentences over 30 words
- Passive voice in instructions
- Undefined acronyms

4. Include Actionable Guidance

Tell the LLM what to do with the skill, not just what the skill is about:

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

Verification Checklist

• [ ] Prompt frontmatter lists skill paths (skills: ./skills or explicit files)
• [ ] Each skill has a clear, descriptive description in frontmatter
• [ ] Skill body contains actionable instructions
• [ ] Prompt file mentions load_skill in the system message
• [ ] Listed paths resolve relative to the prompt file
• [ ] Prompts that should load no skills omit skills (or set skills: [])
• [ ] Skills are focused (one area of expertise per file)
• [ ] Prompt frontmatter sets maxSteps when the tool-loop ceiling should not be 10

Related Skills

• output-dev-prompt-file - Creating .prompt files that use skills
• output-dev-agent-class - Using the Agent class with skills
• output-dev-step-function - Using skills in step functions
• output-dev-folder-structure - Understanding skill file locations