Skill Scripts and Packaging skill for Codex

Supporting files are worth adding only when they make Codex faster or more correct than prose would. A well-packaged skill keeps SKILL.md as the procedure, pushes rarely needed depth into references the body points to conditionally, uses scripts for deterministic work that runs offline in the sandbox, and installs by copying one folder.

Layout

my-skill/
├── SKILL.md              # required: frontmatter + procedure
├── scripts/              # deterministic helpers Codex runs
├── references/           # depth Codex reads only in some branches
├── assets/               # templates, schemas, fixtures used to build output
└── agents/
    └── openai.yaml       # optional: UI metadata, invocation policy, tool dependencies

Every file must be mentioned in SKILL.md with when and how to use it; an unmentioned file is invisible to the agent.

Decide what goes where

Content	Put it in	Signal
Steps, decisions, gotchas used on every run	SKILL.md	Needed > 50% of the time
Long catalogs, API tables, edge-case playbooks	references/<topic>.md	Needed in one branch; would push SKILL.md past ~300 lines
Parsing, validation, measuring, file generation	scripts/	Same input should always give the same output
Output templates, JSON Schemas, config skeletons	assets/	Copied or filled, not read for guidance
Display name, icon, implicit-invocation switch, MCP dependency	agents/openai.yaml	Product surface or policy, not instructions

Prefer instructions over scripts unless the task needs determinism or the agent keeps getting a mechanical step wrong.

Workflow

- [ ] 1. Identify the deterministic steps worth scripting
- [ ] 2. Write each script to the contract below
- [ ] 3. Test scripts with fixtures, offline, in the sandbox
- [ ] 4. Link scripts and references from SKILL.md with exact commands and conditions
- [ ] 5. Add agents/openai.yaml if policy or dependencies require it
- [ ] 6. Package and share

2. Script contract

• Standard library only (Python 3.10+, POSIX sh, or Node 20+). If a dependency is truly required, check for it and print the install command instead of failing obscurely.
• Shebang line, --help, arguments instead of hard-coded paths.
• Paths in SKILL.md are relative to the skill folder; scripts must not assume the cwd is the skill folder. Resolve their own location when they need sibling files:

  HERE = Path(__file__).resolve().parent
  template = (HERE.parent / "assets" / "report.md").read_text()

• Output: a short human summary on stdout, details on demand (--json); errors to stderr.
• Exit 0 on success, 1 on a failed check, 2 on usage errors. Codex reads exit codes.
• Read-only by default; write only to paths passed as arguments; never delete outside them.
• No network unless the skill says so, because Codex usually runs with network off. If a script needs network, say “needs network; ask the user to approve or run it” in SKILL.md.
• Idempotent: running twice gives the same result.
• Bounded output: truncate long listings with a count, so the result does not flood context.

3. Test

python3 scripts/check_thing.py --help
python3 scripts/check_thing.py tests/fixtures/good.json; echo "exit=$?"   # expect 0
python3 scripts/check_thing.py tests/fixtures/bad.json;  echo "exit=$?"   # expect 1
codex sandbox macos -- python3 scripts/check_thing.py tests/fixtures/good.json   # or: codex sandbox linux

The last line runs it under the same sandbox Codex uses, catching scripts that write to $HOME, open sockets or rely on tools outside the sandbox. Test with the oldest interpreter version you claim to support.

4. Link from SKILL.md

## Validate the manifest
Run `python3 scripts/check_manifest.py <path>`. Exit 1 lists each violation; fix them
and rerun until it exits 0.

Read [references/manifest-fields.md](references/manifest-fields.md) only when the
check reports an unknown field.

Give the exact command, what success looks like, and what to do on failure. Keep references one level deep: SKILL.md links to references, references do not chain to more references.

5. agents/openai.yaml

interface:
  display_name: "Release Notes"
  short_description: "Draft release notes from merged PRs"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#3B82F6"
  default_prompt: "Draft release notes since the last tag"
policy:
  allow_implicit_invocation: false   # only via $release-notes or /skills
dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

allow_implicit_invocation defaults to true. Set it to false for skills with side effects (deploys, data changes) so they only run on request. Declared MCP dependencies let Codex offer to install a missing server (feature skill_mcp_dependency_install, on by default).

6. Share

Audience	Method
Everyone working in one repo	Commit to .agents/skills/<name>/; review changes like code
Just you, all repos	Copy or symlink into ~/.agents/skills/<name>/ (symlinks are followed)
A machine or container image	/etc/codex/skills/<name>/
Curated public skills	$skill-installer <name> installs from the curated catalog or a repo you point it at
Other teams, with versioning, or bundled with MCP servers	Package as a plugin (see codex-plugin-packaging)

Before sharing: remove secrets, internal hostnames and personal paths; make scripts executable (chmod +x scripts/*); lint the folder (the skill-authoring skill ships a checker); note runtime requirements in SKILL.md.

Gotchas

• Skill scripts can raise their own approval prompts; with a granular approval policy, skill_approval = false auto-rejects them, so the script step silently fails in that setup. Document a manual fallback.
• $skill-installer and plugin installs bring third-party instructions and code onto the machine. Read SKILL.md and every script before first use.
• A script that prints thousands of lines costs more context than the prose it replaced.
• Repo skills travel to Codex Cloud tasks; scripts there run in the cloud environment, so their tool requirements must be met by that environment’s setup.
• Binary assets bloat the repo and the zip; keep icons small and avoid large fixtures.

Output contract

**Skill:** release-notes
**Added:** scripts/collect_prs.py (stdlib, exit 0/1/2, tested on 3 fixtures and under codex sandbox), references/conventional-commits.md (linked conditionally), agents/openai.yaml (implicit invocation off)
**Shared via:** .agents/skills in repo (PR #412)