output-dev-skill-file

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/
    ├── [email protected]
    └── 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.