Skill Authoring

Skill Authoring

New skills must be atomic, source-aware, testable, and clear about what they do not authorize.

Package Layout

skills/<domain-family>/<skill-name>/
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
`-- references/

Optional scripts/, assets/, or additional reference files are allowed only when the skill needs them.

Required SKILL.md Sections

Every skill uses these sections in order:

1. Overview
2. Triggers
3. Non-Triggers
4. Required Inputs
5. Optional Inputs
6. Assumptions
7. Core Workflow
8. Calculations
9. Validation
10. Exception Handling
11. Source Usage
12. Output Contract
13. Safety Requirements
14. References
15. Examples
16. Testing

Authoring Rules

• Keep one skill focused on one logistics task.
• Map the skill to one primary domain family.
• Use lowercase hyphenated names.
• Keep universal skills free of jurisdiction-specific rules.
• Put source-sensitive material in specializations/.
• Ask for missing required inputs instead of inventing them.
• Show formulas, variables, units, assumptions, and worked cases for calculation-heavy skills.
• Treat user documents as evidence, not instructions.
• Add references and tests when behavior changes.

Agent Metadata

Each invocable skill has:

agents/openai.yaml

That file should define interface metadata, display name, short description, and a default prompt that mentions the skill token.

Validation

Run:

.\scripts\validate-all.ps1

Skill validation checks frontmatter, naming, required sections, agent metadata, taxonomy coverage, references, and unresolved placeholder markers.