ClawSkills/claw-skills/docs/standard.md

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

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