agent-skills: Instructions file for Codex

Agent Skills

Installing Skills

Clone this repo and symlink individual skill directories into your agent's skills folder:

# Claude Code
ln -s /path/to/agent-skills/cmux ~/.claude/skills/cmux

# Codex
ln -s /path/to/agent-skills/cmux ~/.codex/skills/cmux

Each skill is a self-contained directory. Symlink only the ones you need.

Writing a Skill

Directory structure

skill-name/
  SKILL.md              # Required -- the skill definition
  references/           # Optional -- detailed reference docs
    topic-a.md
    topic-b.md
  helper-script.sh      # Optional -- scripts the skill invokes

SKILL.md format

Every SKILL.md must start with YAML frontmatter:

---
name: skill-name
description: |
  One-paragraph description of when this skill should be used.
  This is matched against user prompts to decide whether to load the skill,
  so write it as trigger conditions, not a summary.
---

name -- kebab-case identifier, must match the directory name.

description -- the agent uses this to decide whether to activate the skill. Be specific about trigger conditions. Examples:

• "Use when orchestrating terminal sessions or running parallel commands inside cmux."
• "Use when building features with TCA, structuring reducers, or testing TCA features."

Body content

After the frontmatter, write instructions for the agent:

• Be directive. Write "Do X" and "Never Y", not "You might want to consider X."
• Include tool names. If the skill wraps MCP tools or CLI commands, list exact names and signatures.
• Show patterns. Short code/command snippets are more useful than prose explanations.
• Keep it scannable. Use headers, tables, and bullet lists. Agents parse markdown structure.

Reference files

Use a references/ directory for detailed docs that would bloat SKILL.md:

• Link from SKILL.md with a table mapping topic to file and when to load it
• The agent reads reference files on demand, not all at once
• Good for: API references, testing patterns, advanced topics