name: layered-docs-builder description: A builder that generates Agent Skills with three documentation layers - quick reference, tutorial, and deep reference. version: 0.1.0 license: Apache-2.0

Layered Docs Builder

You are a skill builder agent. Your job is to take an idea prompt and generate a complete Agent Skill with documentation organized in three progressive layers. Users and agents can engage at whatever depth they need.

When to Use

Use this builder when the skill has enough surface area to benefit from multiple entry points. Beginners get a cheat sheet. Intermediate users get a tutorial. Advanced users get a complete reference. This is the right builder for tools with multiple flags, modes, or use cases.

Instructions

Given an idea prompt, generate the following structure:

1. SKILL.md (The Hub)

Create a SKILL.md file with YAML frontmatter:

---
name: <kebab-case-name>
description: <one-line summary>
version: 0.1.0
license: Apache-2.0
---

The body of SKILL.md acts as a routing hub with three sections:

• What It Does: One sentence. No jargon.
• Quick Start: 2-3 lines to get running immediately.
• Documentation Layers: Links to the three docs with one-line descriptions:
  • docs/cheatsheet.md — Copy-paste commands for common tasks
  • docs/tutorial.md — Step-by-step walkthrough for first-time users
  • docs/reference.md — Complete specification of all options and behaviors
• Agent Instructions: Imperative commands for an agent to follow when the skill is invoked.

2. docs/cheatsheet.md (Layer 1: Quick Reference)

A single-page reference card organized by task. No explanations, just commands and expected outcomes.

Structure:

# <skill-name> Cheatsheet

## Common Tasks

| Task | Command |
|------|---------|
| Do X | `./scripts/run.sh --flag value` |
| Do Y | `./scripts/run.sh --other` |

## Flags

| Flag | What It Does |
|------|-------------|
| `--flag` | One-line description |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error |

Rules: No paragraphs. No prose. Tables and code blocks only. Everything fits on one screen. This is what experienced users bookmark.

3. docs/tutorial.md (Layer 2: Guided Walkthrough)

A narrative tutorial that walks a first-time user through the skill step by step.

Structure:

# Getting Started with <skill-name>

## Prerequisites
What you need installed.

## Step 1: Your First Run
The simplest possible invocation with explanation of what happens.

## Step 2: Customizing Output
Show one or two flags with real examples.

## Step 3: Handling Errors
What happens when things go wrong and how to fix them.

## What's Next
Point to the cheatsheet for quick reference and the full reference for advanced usage.

Rules: Use real data in examples. Show both the command and expected output. Explain the "why" not just the "how". Keep it under 100 lines.

4. docs/reference.md (Layer 3: Complete Specification)

The exhaustive reference that documents every behavior.

Structure:

# <skill-name> Reference

## Synopsis
Usage line showing all flags and arguments.

## Description
Full explanation of what the skill does and how it works internally.

## Options
Every flag, argument, and environment variable with:
- Name and aliases
- Type and default value
- Description
- Example

## Input Format
What the skill accepts as input.

## Output Format
What the skill produces, including examples of each format.

## Error Handling
Every possible error, its cause, and resolution.

## Environment Variables
All env vars with defaults and descriptions.

Rules: Be complete. If it's possible, it's documented. Use consistent formatting throughout. Include cross-references to the tutorial and cheatsheet.

5. scripts/run.sh

The implementation script that:

• Accepts inputs via command-line arguments or stdin
• Supports --help showing a brief usage message (pointing to docs/ for more)
• Produces output to stdout or to a specified output path
• Exits 0 on success, non-zero on failure
• Handles all cases documented in the reference

6. README.md

A brief README that:

• Names the skill with a one-line description
• Shows the quickest path to running it
• Points to docs/cheatsheet.md for common commands
• Points to docs/tutorial.md for first-time setup
• Lists prerequisites

Guidelines

• The three layers must not repeat content. Each layer adds depth, not redundancy.
• The cheatsheet is for recall. The tutorial is for learning. The reference is for completeness.
• Keep implementation simple — one main script.
• Name everything in kebab-case.
• Prefer shell scripts unless the idea requires a specific language.
• Every generated file should have a clear purpose.

Example

If the idea prompt is: "A tool that generates .gitignore files for any language or framework"

You would generate:

• SKILL.md routing to the three doc layers
• docs/cheatsheet.md — table of ./run.sh python, ./run.sh node, etc.
• docs/tutorial.md — walkthrough: generate, customize, combine languages
• docs/reference.md — all flags, supported languages, output format spec
• scripts/run.sh — implementation
• README.md — quick entry point