codex-meta

Category: Tools & Productivity | Uploader: michaelschade | Downloads: 0 | Version: v1.0（Latest）

Use when the user wants to understand, design, or improve Codex itself: hooks, subagents, skills, AGENTS.md or PLANS.md guidance, desktop deeplink routing, config-aware workflow design, Codex docs navigation, or deciding when to use codex exec, the SDK, App Server, GitHub Action, or automation. Inspect the current local Codex setup before recommending repo- or machine-scoped changes.

Changelog: Source: GitHub https://github.com/michaelschade/codex-goodies

Directory Structure

Current level: tree/main/skills/codex-meta/

📁 agents/
- 📄 openai.yaml 833 B
📁 references/
- 📄 codex-local-state.md 11.7 KB
- 📄 codex-programmatic.md 21.9 KB
- 📄 codex-system.md 27.7 KB
📄 README.md 2.0 KB
📄 SKILL.md 7.6 KB

SKILL.md

---
name: "codex-meta"
description: "Use when the user wants to understand, design, or improve Codex itself: hooks, subagents, skills, AGENTS.md or PLANS.md guidance, desktop deeplink routing, config-aware workflow design, Codex docs navigation, or deciding when to use codex exec, the SDK, App Server, GitHub Action, or automation. Inspect the current local Codex setup before recommending repo- or machine-scoped changes."
---

# Codex Meta

Use this skill for Codex-system questions and docs-grounded workflow design.

Use it when the hard part is not just wording, but how Codex surfaces such as hooks, skills, subagents, or automations should be shaped and related.

Keep this file lean. Load deeper references only when they are actually needed:

- [references/codex-system.md](references/codex-system.md) for surface choice, hooks, subagents, desktop deeplinks, memories, config, and grouped doc scaffolding
- [references/codex-programmatic.md](references/codex-programmatic.md) for `codex exec`, the SDK, App Server, GitHub Action, and embedded or CI Codex workflows
- [references/codex-local-state.md](references/codex-local-state.md) for privacy-safe self-inspection of local Codex sessions, rollouts, memories, logs, automations, and SQLite state

## Use this skill for

- hooks, subagents, skills, `AGENTS.md`, `PLANS.md`, and Codex workflow design
- prompting or documenting Codex-specific surfaces such as hooks, skills, subagents, or automations when the surface itself is the design question
- desktop self-linking and deeplink design when Codex should open its own settings, skills, automations, or a new chat with prefilled context
- deciding what belongs in prompts versus Codex surfaces
- docs-guided recommendations about current Codex capabilities, surfaces, and setup
- deciding when a workflow should move into `codex exec`, the SDK, App Server, GitHub Action, or automation
- privacy-safe introspection of local Codex history and state when the task is about improving Codex using prior sessions, rollout artifacts, logs, memories, or automation state

## Core rules

### 1. Inspect live local context when the scope is local

Before recommending repo- or machine-scoped changes, inspect the relevant live setup instead of guessing from older context.

Start with:

- the active runtime surface when the question is thread-, automation-, or sandbox-scoped
- the installed desktop client when the question is about `codex://` deeplinks or app-local routing behavior
- `~/.codex/hooks.json`
- `~/.codex/agents/*.toml`
- directly relevant local skills under `~/.codex/skills/`
- repo-local `AGENTS.md`, `PLANS.md`, or repo skills when the task is repository-scoped

### 2. Pick the right Codex surface

- Decide whether the fix belongs in a prompt, `AGENTS.md`, a skill, a hook, config, a subagent, automation, or a programmatic Codex surface.
- If repeated prompt tweaks are not fixing the goal, step back and diagnose whether the real issue is surface choice, missing context, invocation shape, tool design, or evaluation.
- Keep durable behavior in the right layer instead of re-explaining it in ad hoc prompts.

### 2.5 Treat local `~/.codex` findings as approval-gated

- Anything derived from inspecting local `~/.codex` state is private by default.
- You may use local `~/.codex` artifacts for diagnosis, private analysis, or identifying possible patterns.
- Do not document new concepts, features, product behavior, or reusable guidance into this skill from local `~/.codex` evidence unless the user explicitly approves that documentation step.
- If local evidence suggests an interesting new concept or behavior, stop before editing public-bound skill content and ask for permission to promote that lesson into the skill.
- Prefer official OpenAI docs and other public sources for durable skill guidance. Treat local `~/.codex` evidence as a private hint or validation layer, not an automatic source for public documentation.

### 3. Keep hooks thin and pick the right Codex surface

- Hooks are for concise lifecycle context injection, light plumbing, or crisp objective guardrails.
- Do not use hooks as semantic planners, prompt classifiers, or hidden workflow engines.
- If nuanced judgment is required, prefer better model-facing instructions, better surface choice, better agent design, or a better evaluation loop.
- Once a surface is chosen, keep its prompt or instructions specific to that surface: hook text should be terse and objective, skill guidance should define one reusable job, subagent briefs should set ownership and proof expectations, and automation prompts should describe the durable task rather than the schedule.
- Use `$prompt-writing` when the surface is already chosen and you need to write or refine the model-facing prompt or instructions so they fit the intended goal, runtime, and terminology.
- Load [references/codex-system.md](references/codex-system.md) when the hard part is surface choice across hooks, `AGENTS.md`, skills, subagents, config, MCP, worktrees, memories, or automations.
- Load [references/codex-programmatic.md](references/codex-programmatic.md) when the hard part is `codex exec`, the SDK, App Server, GitHub Action, or Codex as infrastructure inside a larger system.

### 4. Use live docs only when facts may have drifted

Use live docs only when the recommendation depends on drift-sensitive facts such as:

- current model names or preferred families
- current Codex feature behavior
- newly released guides or docs that may supersede older local guidance

Prefer official OpenAI sources. If `$openai-docs` is available, prefer it. Use the local references above to keep the main skill small and load live docs only when the details are likely to have changed.

## Workflow

Choose the primary docs-and-surface question first. Keep the work anchored on setup, architecture, local context, and current docs.

### 1. Clarify the hard part

- surface choice across prompts, skills, hooks, subagents, config, memories, or automation
- surface-specific prompt shaping for hooks, skills, subagents, or automations
- programmatic Codex usage such as `codex exec`, the SDK, App Server, or GitHub Action
- privacy-safe learning from local rollouts, memories, logs, or automation state
- docs navigation or drift-sensitive Codex recommendations

### 2. Inspect the relevant local setup

- inspect the current local setup before recommending repository-scoped or machine-scoped changes
- for automation, sandbox, or approval questions, first identify whether the work is thread-attached or a fresh project run and what posture that surface inherits by default
- use only the surfaces that materially change the recommendation
- keep incidental local context out of any public-bound guidance

### 3. Load the right reference

- Load [references/codex-system.md](references/codex-system.md) when the hard part is surface choice, hooks, subagents, config, memories, or doc-map guidance.
- Load [references/codex-programmatic.md](references/codex-programmatic.md) when the hard part is CI, structured automation, embedded Codex, custom clients, or Codex as infrastructure.
- Load [references/codex-local-state.md](references/codex-local-state.md) when the hard part is learning from local rollout artifacts, session files, memories, logs, automations, or SQLite state without leaking sensitive content.

### 4. Keep the recommendation surface-shaped

- Separate architecture guidance from any follow-on artifact writing.
- If the surface is already chosen and you need to refine the model-facing prompt or instructions for that surface, hand that work to `$prompt-writing`.
- Keep the final recommendation concise enough that a later implementation, config edit, or prompt draft can pick it up cleanly.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

codex-meta

Directory Structure

SKILL.md

Report

Notice