2.9 KiB
2.9 KiB
Instruction-Design Glossary
Use these terms when they clarify a discussion about agent instructions. They are concepts, not a requirement to avoid ordinary synonyms. SKILL.md owns the workflow and Codex invocation mechanics.
Discovery and cost
- Predictability: comparable situations lead to consistent, task-appropriate decisions.
- Model-invoked: available for automatic selection as well as explicit invocation.
- User-invoked: explicitly selected; an explicit-only policy disables automatic selection, not required metadata.
- Description: required frontmatter that summarizes capability and applicability; it is not the invocation-policy toggle.
- Context pointer: a reference plus the condition for reaching its target.
- Context load: tokens and attention spent on available metadata and loaded instructions.
- Cognitive load: what the human must remember or decide to use the system.
- Router skill: selects among genuinely distinct workflows or resources.
- Granularity: how finely instructions are divided; each split must justify its discovery and maintenance cost.
Information hierarchy
- Steps: ordered actions where sequence matters to the task.
- Reference: definitions, constraints, or procedures consulted when relevant.
- External reference: material outside the entrypoint, reached through an appropriate pointer.
- Information hierarchy: the placement of essential actions and constraints versus conditional detail.
- Progressive disclosure: loading supporting detail only when the task needs it.
- Co-location: keeping a concept's definition, rules, and caveats together.
- Branch: a distinct case or mode handled by the skill.
Execution and maintenance
- Leading word: a compact, familiar concept that conveys a useful decision principle without repeated explanation.
- Completion criterion: evidence that the requested outcome has been reached; it should be checkable and cover the important requirements.
- Legwork: investigation needed to meet that criterion rather than transferring discoverable work to the user.
- Post-completion steps: later actions that may distract from an unfinished prerequisite.
- Premature completion: declaring a step or task done without meeting its criterion. Clarify the criterion before adding process.
- Negation: wording framed around what to avoid. Prefer a clear positive target where possible while retaining necessary safety prohibitions.
- Single source of truth: one authoritative home for a rule or fact.
- Duplication: repeated meaning that must be maintained in several places.
- Relevance: whether material still supports the skill's actual task.
- Sediment: stale assumptions accumulated through updates.
- Sprawl: more instruction volume than the task usefully needs.
- No-op: wording that does not materially change the agent's decisions or work.