41 lines
2.9 KiB
Markdown
41 lines
2.9 KiB
Markdown
# 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](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.
|