Field guide / 15 min
Package repeatable work as skills
Use a focused SKILL.md for the workflow; use a plugin when distribution and connections matter.
Skills package instructions, references, scripts, and optional assets. Codex discovers them through concise metadata and loads full instructions only when selected. Plugins distribute skills and optional MCP connections through configured marketplaces; list and review a marketplace before installing a named plugin.
Verified terminal sequence
- ›
$skill-creator - ›
/skills - ›
$skill-name - $
codex plugin marketplace list - $
codex plugin marketplace add owner/repo --ref main - $
codex plugin list - $
codex plugin add <PLUGIN>@<MARKETPLACE>
Working principles
One skill, one job
A precise description improves both explicit selection and implicit triggering.
Progressive disclosure
Metadata is cheap and always visible; SKILL.md, references, and scripts load only when needed.
Distribution is separate
Author locally first. Package as a plugin when other people need installation, multiple skills, or connectors.
Marketplace is a trust decision
Review the Git or local source and enumerate available plugins before adding one to local configuration and cache.
Field procedure
- 01
Define the trigger
Write when the skill should and should not run before describing its procedure.
- 02
Use the creator
Invoke $skill-creator, then inspect the generated SKILL.md rather than accepting boilerplate.
- 03
Keep deterministic helpers narrow
Add scripts only when deterministic processing is more reliable than prose instructions.
- 04
Test explicit and implicit use
Invoke with $skill-name, then try realistic prompts that should and should not trigger it.
- 05
Choose distribution
Keep repository workflows in .agents/skills; build a plugin only for stable shared installation.
- 06
Exercise the install path
List configured marketplaces and available plugins, add one explicit plugin selector, then verify the installed capability and remove it when the lab ends.
PASS / FAIL
Acceptance checklist
- Description names scope and trigger.
- Inputs, outputs, and verification are explicit.
- Scripts do not hide unnecessary authority.
- Marketplace origin and plugin selector are reviewed.
- Plugin packaging has a real distribution need.
WATCH / REJECT
Failure patterns
- Building a giant universal skill.
- Using custom prompts for new reusable workflows.
- Adding scripts where instructions are sufficient.
- Installing from an unreviewed marketplace because a plugin name looks familiar.