# Skill Authoring Standard

## Anatomy of a Skill

A skill is a directory with up to four layers:

```
{skill-name}/
  SKILL.md            # Required — the menu
  scripts/            # Optional — the kitchen tools
  workflows/          # Optional — the recipes
  docs/               # Optional — the reference manual
```

Each layer has a single responsibility:

| Layer | Role | Analogy | Contains | Does NOT contain |
|-------|------|---------|----------|------------------|
| **SKILL.md** | Router | Menu | What's available + when to use it | Process details, standards, how-tos |
| **scripts/** | Automation | Kitchen tools | Fixed-logic executables | Judgment calls, contextual decisions |
| **workflows/** | Process guide | Recipes | Step-by-step procedures requiring judgment | Standards, naming rules, structure specs |
| **docs/** | Reference | Reference manual | Facts, standards, specifications | Procedures, step-by-step instructions |

### How they relate

```
Agent reads SKILL.md
  → finds the right script or workflow
    → workflow references docs/ for standards when needed
```

## SKILL.md — The Menu

SKILL.md is the first thing an agent reads. It answers two questions: **what's available** and **when to use it**.

### Format

```markdown
---
name: {skill-name}
description: {one-line description of when to use this skill}
---

> Execution notes (e.g., "All scripts must be executed via pcexec")

## Scripts

List each script with invocation syntax and a one-line description.
Group related scripts under a subheading if needed.

## Workflows

List each workflow file path with the trigger condition (when to use it).

## Reference

Point to docs/ if the skill has reference material.
```

### Rules

- **Concise.** One-line descriptions per script/workflow. No multi-paragraph explanations.
- **No process details.** Don't describe how to do something — that belongs in workflows/.
- **No standards or rules.** Don't define naming conventions or structure — that belongs in docs/.
- **Warnings and prerequisites** are allowed as short callouts (e.g., "do not run unless explicitly requested").

## scripts/ — The Kitchen Tools

Scripts handle operations that are **completely fixed** — the steps are predictable, the logic doesn't change based on context.

### Rules

- Each script has a single responsibility
- Must be executable (`chmod +x`)
- Must be called via `pcexec` unless documented otherwise
- Use `AGENT_ID`, `AGENT_WORKSPACE` environment variables when behavior varies by agent
- Use `ego-mgr get <field>` for agent identity info inside scripts

## workflows/ — The Recipes

Workflows guide operations that **require judgment** — the steps vary depending on context, or decisions need to be made along the way.

### Rules

- Each workflow is a standalone markdown file
- Must be self-contained enough to follow independently
- Reference docs/ for standards (e.g., `> See docs/standard.md for naming conventions`) — don't repeat them inline
- Focus on **steps and decision points**, not rules

## docs/ — The Reference Manual

Docs hold **facts and standards** that don't change based on who's reading or what task they're doing.

### Rules

- Reference material only — no step-by-step procedures
- Standards, specifications, naming conventions, structure definitions
- Referenced by workflows and SKILL.md, never duplicated into them

## General Requirements

- **Language:** All skill documentation must be written in English
- **Naming:** Skill directories use kebab-case (e.g., `git-hangman-lab`)
- **Frontmatter:** SKILL.md must start with a YAML frontmatter block containing `name` and `description`