Skills Guide

Skills are reusable local workflows. A skill is rooted at a SKILL.md file and describes a repeatable task pattern that an agent can load when needed.

What a Skill Is

A skill typically contains:

• Purpose — What task the skill helps with
• Workflow — Step-by-step guidance for the agent
• Boundaries — What the skill should and should not do
• References — Related files or commands to inspect

Skills are not automatically active. The runtime exposes a catalog of available skills, and the agent opens the relevant SKILL.md only when a matching task appears.

Location

Repository-local skills commonly live under:

.codex/skills/<skill-name>/SKILL.md
skills/<skill-name>/SKILL.md

Example skills in this repository include:

• ghx
• github-issue-solve
• github-pr-fix
• github-review

How Agents Use Skills

1. The runtime exposes a skills catalog with name, description, and path
2. The agent chooses a skill only if it matches the current task
3. The agent reads the skill's SKILL.md
4. The agent follows the workflow with normal tool calls

This keeps skills explicit and avoids loading irrelevant guidance.

Installing and Listing Skills

The HTTP control plane exposes skill endpoints:

• GET /agents/:agent_id/skills — List installed or available skills
• POST /control/agents/:agent_id/skills/install — Install a skill
• POST /control/agents/:agent_id/skills/uninstall — Remove a skill

Writing a Good Skill

Keep skills:

• Small — Focus on one workflow
• Actionable — Give concrete steps the agent can execute
• Scoped — Avoid broad project-overriding instructions
• Durable — Encode reusable behavior, not one-off task notes

Good skill topics:

• GitHub issue solving
• PR review workflow
• Release checklist
• Incident triage
• Project-specific test/debug loop

Poor skill topics:

• Temporary meeting notes
• One-off task plans
• Large copied documentation dumps

Relationship to AGENTS.md

Use:

• AGENTS.md for durable role, authority, and local conventions
• Skills for reusable workflows
• Work items for current tracked objectives

These are different layers:

See Also

• Multi-Agent Collaboration — Delegating work to child agents
• Work Items Guide — Tracking durable objectives
• Runtime Model — How skills fit into the agent operating loop