codexception

Codexception

Use this skill to decide whether recent work should be codified into a reusable Codex skill, then create or update that skill in ~/.codex/skills or the project-local .codex/skills directory.

Codexception is a Codex-native fork of Claudeception. It keeps the original package's explanation, examples, templates, and research notes, while making the runtime contract Codex-specific: Codex skill paths, Codex hooks, and Codex validation expectations are authoritative here.

When To Extract

Extract only when all are true:

• •Reusable: future similar tasks would be faster or safer with this knowledge.
• •Non-obvious: the answer required investigation, debugging, or local context.
• •Specific: there are clear trigger conditions, symptoms, file paths, commands, or workflows.
• •Verified: the solution or workflow was tested, or the remaining risk is explicit.

Before writing or updating a skill, apply this utility gate:

• •Failure mechanism: capture why the previous attempt failed or why the

workflow is easy to get wrong. Avoid vague lessons like "be careful" or "check thoroughly."

• •Actionable specificity: include concrete commands, APIs, portable file

references, environment constraints, decision rules, or step order that a future agent can execute directly. For files bundled with a skill, use paths relative to the skill directory. Do not bake in local absolute paths with usernames, machine names, or other host-specific details.

• •High-risk blacklist: explicitly forbid actions that are likely to corrupt

state, erase user work, bypass validation, create false evidence, or overfit a one-off workaround.

• •Behavior preservation: when updating an existing skill, identify the

current useful behavior that must survive the edit. Do not fix one failure by erasing a verified workflow.

Do not extract for simple command output, generic docs lookup, one-off Jira state, or unverified guesses. If rejecting a tempting extraction because it is too weak, record at most a one-sentence rejected reason in temporary working notes only when it would prevent repeating the same bad extraction later.

Workflow

1. Finish the user's task first.
2. Ask:

- What was discovered that was not obvious at the start? - What exact future trigger should load this knowledge? - What steps or checks prevent repeating the investigation? - What verification proved it works? - What dangerous or misleading action should the skill explicitly prohibit?

1. If the answer is strong, create a focused skill.
2. If the knowledge is project-specific, prefer a project/domain skill over a broad generic one.
3. For an existing mature skill, prefer one bounded append, replace, or delete.

Do not rewrite the whole skill unless the old structure is the verified failure mechanism.

1. Keep the skill concise. Put only operational knowledge in SKILL.md.
2. Run the post-write validation checklist before considering the extraction done.

Bundled References

Use the bundled files only when they help the current extraction:

• •resources/skill-template.md: copy its structure when creating a new Codex

skill from scratch.

• •examples/: inspect one nearby example when you need a concrete model for

trigger wording, procedure scope, or verification style.

• •scripts/codexception-activator.sh: source copy for the global hook at

~/.codex/hooks/codexception-activator.sh.

Codex Skill Format

Create:

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

Use YAML frontmatter with name and description; the description is the retrieval surface, so include concrete trigger phrases and technologies. When referencing files bundled with the skill, prefer skill-relative paths such as scripts/helper.py. Avoid local absolute paths with usernames, machine names, or private mount points.

Template:

---
name: kebab-case-name
description: |
  What this skill does. Use when: exact symptoms, commands, file paths,
  error messages, project names, or workflow triggers.
---

# Human Title

## Use When

- Exact symptom, request phrase, error text, or workflow condition.
- Environment constraint that makes the skill relevant.

## Failure Mechanism

Explain why the obvious fix fails.

## Procedure

1. ...

## Verification

- ...

## High-Risk Actions

- ...

## Notes

- ...

Post-Write Validation

Before finishing, verify:

• •The YAML frontmatter is present and the description contains concrete trigger

phrases, technologies, symptoms, or workflow names.

• •The skill has a clear Use When or equivalent trigger section.
• •The procedure is executable by a future agent without relying on hidden context.
• •Verification steps or explicit residual risk are included.
• •High-risk actions are prohibited where relevant.
• •Existing useful behavior was preserved when updating a skill.
• •No local usernames, private absolute paths, machine names, credentials, or

one-off incident details were baked into reusable instructions.

Native Codex Integration

Codex supports command hooks when features.hooks = true is enabled in ~/.codex/config.toml. Register a lightweight SessionStart hook in ~/.codex/hooks.json to remind Codex once per session to evaluate skill extraction after meaningful work:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -lc 'exec \"$HOME/.codex/hooks/codexception-activator.sh\"'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Keep the hook output concise. It should only remind Codex to evaluate whether codexception applies; the skill still decides whether a new reusable skill is warranted.

For Codex CLI versions that require structured hook output, the hook command must emit JSON with hookSpecificOutput.hookEventName set to SessionStart; place the reminder in additionalContext:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "[codexception]\nAfter completing this user request, evaluate whether the work produced reusable knowledge worth preserving as a Codex skill."
  }
}