Table of Contents

Use Spec Kitty in Codex CLI

Tier: first_class — heaviest Agent Skills integration. Citation (accessed 2026-05-21): https://github.com/openai/codex

Prerequisites

  • Spec Kitty CLI installed. See Install Spec Kitty.
  • Project initialized for this harness: 
    spec-kitty init --ai codex
  • Codex CLI installed and authenticated. Follow the openai/codex README for installation and login.

Where Spec Kitty installs files

Per the supported-harnesses matrix, Codex CLI consumes Spec Kitty as Agent Skills (not slash commands). Spec Kitty installs:

  • Directory: .agents/skills/spec-kitty.<command>/
  • Files: one SKILL.md per command (spec-kitty.specify/SKILL.md, spec-kitty.plan/SKILL.md, spec-kitty.tasks/SKILL.md, spec-kitty.implement/SKILL.md, etc.).
  • Manifest: .kittify/command-skills-manifest.json records which agents reference each skill package.

Codex reads the skill tree directly; the same tree is shared with Mistral Vibe via .vibe/config.toml skill_paths.

Canonical invocation

Inside the Codex CLI, skills are invoked with the $ prefix:

$spec-kitty.specify "<one-line mission description>"
$spec-kitty.plan
$spec-kitty.tasks
$spec-kitty.implement WP01

This is the key difference from slash-command hosts — do not type /spec-kitty.* in Codex; use $spec-kitty.*.

Worked example

  1. From your project root, start Codex (codex).
  2. At the prompt, type: 
    $spec-kitty.specify "a hello world page"
  3. Spec Kitty's interview prompts appear — answer them inline.
  4. When asked for a kebab-case slug, supply something short, e.g. hello-world-page.
  5. The mission spec lands at kitty-specs/hello-world-page-<mid8>/spec.md.

Troubleshooting

  • $spec-kitty.* skills do not appear. Run spec-kitty agent config sync from the repo root. This regenerates .agents/skills/spec-kitty.*/SKILL.md from the canonical source templates and re-registers the manifest. Restart Codex.

  • Profile not loading (researcher / reviewer roles do not adopt). At the Codex prompt, run:

    /ad-hoc-profile-load researcher-robbie

    Use the profile id named in the work-package frontmatter (agent_profile:).

Where to learn more about Codex

Authoritative documentation: https://github.com/openai/codex (accessed 2026-05-21). Consult the repository README for the latest Agent Skills syntax and version notes.

Edit this page