zhi
795a710376
Rewrote docs/standard.md as the single source of truth for skill structure (menu/tools/recipes/manual analogy). Trimmed all SKILL.md files to pure routers, moved recruitment workflow out of SKILL.md into workflows/recruitment.md, removed duplicated standards from workflow files. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
# 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`
|