41 lines
3.0 KiB
Markdown
41 lines
3.0 KiB
Markdown
---
|
|
name: writing-great-skills
|
|
description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
|
|
---
|
|
|
|
# Writing Great Skills
|
|
|
|
Write guidance that improves decisions while preserving the user's outcome, choices, and authority. Predictability means handling comparable situations consistently—not imposing the same ceremony on every task.
|
|
|
|
## Codex mechanics
|
|
|
|
Every skill needs YAML `name` and `description`. Keep the description concise: what the skill does, when it applies, and a boundary only where it prevents likely misrouting.
|
|
|
|
Automatic discovery is the default. Set `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for a new explicit-only skill only when the user requests it. Preserve existing invocation policies and unrelated UI/dependency fields.
|
|
|
|
Do not use legacy `disable-model-invocation` or `argument-hint` frontmatter for Codex, or delete descriptions to change invocation. Discovery policy does not grant authority; check authorization at the relevant mutation.
|
|
|
|
## Write only decision-changing guidance
|
|
|
|
- State the intended outcome, non-obvious context, genuine constraints, and a recognizable completion condition.
|
|
- Reuse explicit user choices and known context. Ask only for missing information that materially affects the task.
|
|
- Match specificity to risk: fixed sequences belong in fragile workflows, not ordinary open-ended work.
|
|
- Preserve authority boundaries. A review should not silently implement; a plan should not silently publish. Define stopping and retry behavior where failures or duplicate external writes matter.
|
|
- Keep discovery specific. Avoid exhaustive synonym lists and generic triggers that attract unrelated tasks.
|
|
|
|
## Arrange the information
|
|
|
|
Keep shared purpose and essential constraints in the entrypoint. Move substantial mode-specific procedures behind a link that says when to read them. Keep simple skills self-contained; add a router only for meaningful branches.
|
|
|
|
Use one authoritative home for each rule. Read the environment rather than copying readily discoverable configuration into instructions, except where a local gotcha is worth recording.
|
|
|
|
Use [GLOSSARY.md](GLOSSARY.md) when discussing instruction-design concepts such as context load, progressive disclosure, or premature completion. It defines the vocabulary; this file owns the authoring workflow and Codex mechanics.
|
|
|
|
## Validate and prune
|
|
|
|
Check metadata with the target runtime's validator, confirm references are reachable, and run changed helpers with safe representative inputs. Test observable outcomes and invariants, not exact generated wording.
|
|
|
|
For complex or risky behavior, use a scoped independent evaluation when delegation is available and authorized. Keep fixtures isolated from user work and avoid live side effects.
|
|
|
|
Remove duplicated rules, stale assumptions, speculative scaffolding, and examples that do not clarify a real choice. Preserve safety and operational invariants even when shortening the text. If a task keeps failing, correct the demonstrated cause rather than adding universal ceremony.
|