Agent skills, mxcl-style.
npx skills add --global mxcl/skills$ npx skills add --global mxcl/skills --skill mxcl-readme --agent codex --yes
# ^^ adding a specific skill
$ npx skills add mxcl/skills --list
Available Skills
mxcl-readmemxcl-readme teaches Codex to write READMEs like the pkgx family:
terse, example-led and allergic to filler.
$ codex
> use mxcl-readme and write a README for this repoThe skill pushes Codex to:
- open with the product promise
- show commands before long explanations
- use GitHub admonitions for real caveats
- keep caveats honest and visible
- cut generic marketing language
Tip
It is useful for new READMEs, rewrites and reviews. The review mode is often the most revealing: it catches bland copy quickly.
$ find mxcl-readme -maxdepth 3 -type f | sort
mxcl-readme/SKILL.md
mxcl-readme/agents/openai.yaml
mxcl-readme/references/style.mdSKILL.md contains the trigger and workflow. references/style.md contains
the detailed voice guide extracted from pkgx, dev, pkgm, setup and
teaBASE.
Because this repo is meant to be edited, published and installed at the same time.
$ vim mxcl-readme/references/style.md
$ readlink ~/.codex/skills/mxcl-readme
/path/to/skills/mxcl-readme
# ^^ the installed skill is the repo copyNo copy step. No stale local install. Fewer chances to wonder why Codex ignored the thing you just changed.
Keep each skill self-contained:
SKILL.mdis requiredagents/openai.yamlis marketplace/UI metadatareferences/is for detail Codex should load only when neededassets/is for files used by the skill output
Validate before publishing:
$ python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py mxcl-readme
Skill is valid!Important
If your Python does not have yaml, run the validator in an environment with
PyYAML installed. The skill can still be valid; the validator is just a
Python script.
mxcl-readme
Generate, rewrite or review README.md files in the concise pkgxdev/tea style:
sharp promise, command transcripts, useful caveats and dry human asides.