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 the narrowest durable source location: project-local .codex/skills for project-specific behavior, the owning repo/source skill library for domain tools, or ~/.codex/skills only when the knowledge is broadly reusable across workspaces.

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?
3. Before creating a new skill, search source locations on disk, not only the model-visible Codex skill list. The visible list can be shortened by skill budget limits or omit disabled skills.
4. Search at least the relevant project .codex/skills and .agents/skills, ~/.codex/skills, ~/.claude/skills, and ~/.agents/skills; use find -L or equivalent so symlink projections are visible. Also inspect ~/.codex/config.toml [[skills.config]] entries for enabled = false.
5. If a matching skill source already exists, update or reuse that source instead of creating a duplicate. If the only matching source is disabled, preserve it as the source of truth and report that re-enabling is a separate exposure decision. Include the $skill name or absolute SKILL.md path in the final note so usage tooling can observe the existing disabled source.
6. If the answer is strong and no existing source covers it, create a focused skill.
7. If the knowledge is project-specific, prefer a project/domain skill over a broad generic one.
8. 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.
9. Do not expose a new one-off tool skill through an active global or workspace bridge by default. Keep it in its owning source location unless repeated usage or a command/workflow reference proves it should be active.
10. Keep the skill concise. Put only operational knowledge in SKILL.md.
11. 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

Default broad Codex location:

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

Use this location only when the skill should be globally available. For project/domain-specific skills, prefer the owning project-local .codex/skills or source skill library and leave bridge allowlists unchanged until usage evidence justifies active exposure.

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.
• Existing disabled skill sources were searched before creating a new 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."
  }
}