Skill authoring

A skill is a folder: <name>/SKILL.md plus agents/openai.yaml. Its description decides when it fires. Its body directs the work. Scripts enforce deterministic constraints. Resources hold conditional detail. GOAL.md beside them says why the skill exists and what it values; the rule that tests a value lives only in SKILL.md.

Scope and atomicity

One skill owns one stable invocation decision and one coherent job.

• Keep work together when users ask for it as one capability and its parts share the same context.
• Split work when either part has its own trigger, can run on its own, or makes most runs load instructions they cannot use.
• Do not create a skill or add a branch for one incident. Name the class of behavior that should recur before encoding it.

Invocation

Two modes.

• Model-invoked. Omit disable-model-invocation from SKILL.md and omit policy.allow_implicit_invocation from agents/openai.yaml. The model may fire the skill from its description. Use this when an agent should reach for the workflow on its own.
• User-invoked. Set disable-model-invocation: true in SKILL.md and policy.allow_implicit_invocation: false in agents/openai.yaml. Only a human explicitly naming the skill fires it. Use this for workflows run by hand. The description becomes a short human-facing summary instead of a trigger list.