claude-code-skills: Instructions file for Codex

Repository Instructions

This repository distributes standalone skills for Claude Code and Codex through a collection of small plugins.

Structure

plugins/<plugin>/
├── plugin.json
├── .codex-plugin/plugin.json
├── skills/<skill>/SKILL.md
└── evals/<case>/          # maintainer behavioral evals; never loaded by skills

Root plugin.json is the minimal portable Agent Plugins v1 manifest. .codex-plugin/plugin.json is the current OpenAI host adapter for richer metadata and component pointers. Claude Code discovers the shared skills/ directories through .claude-plugin/marketplace.json; Codex uses .agents/plugins/marketplace.json and the host adapter. Do not add host-specific copies of a skill.

Keep portable manifests limited to the canonical Agent Plugins schema identifier and stable plugin name; optional version, description, and publisher metadata remain in the host adapter to avoid duplicated mutable metadata. Both names and the plugin directory must match. Add portable optional fields only when a concrete cross-client requirement justifies a new canonical owner and matching parity validation.

Skill rules

• Edit the canonical skill only at plugins/<plugin>/skills/<skill>/SKILL.md.
• Give every skill at least one behavioral eval case in plugins/<plugin>/evals/<case>/, in the claude plugin eval format, the default location the official evals documentation recommends. An explicit case prompt starts with Use the <skill> skill. and its graders/skill-fired.md names the same skill. Additional discovery cases use natural wording without a skill identifier and do not replace explicit coverage; negative discovery forbids activation and does not require a skill report verdict. Fixtures are offline and must tempt the boundary they grade; graders prove observable outcomes (files, tool calls, the exact verdict token) rather than self-reported success. Skills never reference eval assets.
• Keep each skill standalone. It must not require another skill, MCP server, task tracker, separately installed coordinator or worker, or shared runtime. A skill may require host-native independent contexts when that is intrinsic to its outcome and it defines an explicit BLOCKED result.
• Skill plugins ship instructions only: no mods, hooks/ directories, or hooks.json files. Executable Claude Code tooling for maintainers lives only in the repository mod .claude/skills/ln-maintainer/; it is never distributed, never required by a skill, and never orchestrates agents (no agent spawning, prompt submission, model calls, or tool registration). CI validation and contract tests stay authoritative when the mod is off.
• Follow SKILL_TEMPLATE.md, the canonical owner of skill format, detailed checklist accounting, self-check, and common report blocks. Preserve individually verifiable obligations and skill-specific verdicts; validate standalone copies against the template.
• Preserve evidence rules, tool-selection guidance, safety gates, verdict mapping, output contract, and residual-risk reporting when simplifying.
• Keep common purpose, constraints, and routing in SKILL.md. Move substantial conditional detail into skill-local references/ when it saves irrelevant reading; link each reference with its trigger and keep each rule in one owner. Add scripts or assets only for a concrete reliability or output need; do not create placeholders or a shared runtime.
• Treat each SKILL.md as the canonical operational document for its workflow: keep rules at the narrowest relevant section, remove filler and duplicated guidance, and avoid volatile values or copied implementation detail unless execution requires them and the authoritative source or update trigger is explicit.
• Prefer capability descriptions over vendor-specific tools. Every required capability needs a credible fallback or an explicit BLOCKED outcome.
• Apply the template's language and size limits without padding. Inspect word volume and repeated rules; remove repetition before splitting conditional detail.
• Preserve user intent and already-granted authorization within each skill's mutation boundary. Prepare a concrete result before required external approval; do not ask again for unchanged authorization. Run proportionate checks and repeat them only for new changes, failures, or unresolved evidence.
• Review and audit skills are read-only. Implementation skills may mutate only the user-approved scope and must retain or discard changes using measured evidence.
• Delivery/test planning, opportunity evaluation, operations investigation, and product outcome evaluation are read-only. Product requirements and interaction design may change only approved product/design artifacts. Acceptance-test building may mutate only the approved test and test-documentation scope and must not repair product code.
• Architecture artifact skills may mutate only explicitly approved architecture documents and must not edit product code or tests, execute migrations, or change external systems.
• Skill review is read-only. Repository, release, and announcement publication may mutate only explicitly approved local and external scope and must preserve their approval gates.