Codex Project & Skill Manager

中文说明

Give Codex a predictable home for new projects, a consistent internal layout, and a skill catalog it can actually use.

The problem and the response

Problem		Response
Codex does not know where a new project should live	→	Detect existing preferences or recommend a future-projects root
Every project uses a different internal layout	→	Choose a single-project or umbrella-project structure
Source material, temporary work, and deliverables get mixed together	→	Separate data, temp, and output by purpose
Skills are scattered and hard to discover	→	Use one approved skills root, categories, and a generated menu
Codex does not know which skill fits the task	→	Search the menu first, then load only the best-matching skills
Useful project lessons disappear when work ends	→	Compare marginal benefit before proposing a skill revision or creation

This repository connects project management and skill management so that Codex can move from one-off task completion to a reusable local working system.

What it manages

Future project placement

The manager reads existing preferences first. If none are present, it recommends a stable root for projects created in the future.

Existing projects are never moved, renamed, or reorganized by this product.

Future project structure

A focused project receives a compact structure:

my-project/
├── AGENTS.md
├── README.md
├── data/
├── temp/
├── output/
└── docs/
    └── ai/
        ├── dev_log.md
        └── experience_candidates.md

Create src and tests only when the project contains code that benefits from them.

An umbrella project keeps shared material at the root and gives each durable subproject its own boundary:

umbrella-project/
├── AGENTS.md
├── README.md
├── data/
├── temp/
├── output/
├── docs/ai/
├── subproject-a/
│   ├── README.md
│   ├── data/
│   ├── temp/
│   └── output/
└── subproject-b/
    ├── README.md
    ├── data/
    ├── temp/
    └── output/

Separate subprojects only when they have meaningfully independent goals, inputs, outputs, or lifecycles. File count alone is not a reason to split.

Skill management

The manager detects an existing user-level skills location or recommends one. It then proposes a catalog structure:

<skills-root>/
├── skills-menu.json
├── SKILLS_MENU.md
├── scripts/
└── <category>/
    └── <skill-name>/
        ├── SKILL.md
        └── agents/
            └── openai.yaml

• skills-menu.json is the machine-readable registry.
• SKILLS_MENU.md is generated from the registry and skill metadata.
• Categories are proposed, not imposed. A proposal is read-only; recording it in the registry is an approved write.
• Existing skills stay in place unless the user approves an exact relocation plan.
• Declining a category or relocation never deletes or disables a skill.

How Codex finds a skill

For each task, Codex should:

1. Scan skill names, trigger descriptions, and outputs in SKILLS_MENU.md.
2. For each distinct task or subrequest, shortlist at most three relevant skills.
3. Read the complete SKILL.md only for shortlisted skills.
4. State the order when multiple skills are complementary.
5. Continue without a skill when there is no good match.
6. Never bulk-load all skills or route by category name alone.

How skills improve

At a meaningful project milestone, Codex compares new evidence with the closest existing skills:

Decision	Meaning
Reuse	An existing skill already covers the workflow
Revise	The boundary is the same, but a durable rule or validation method is new
Create	The workflow has a materially distinct trigger or completion contract
Do not skill	The lesson is project-specific or has no proven marginal benefit

Codex asks before creating, revising, moving, classifying, or promoting any user skill.

First use

Open this repository in Codex and ask:

Inspect my Codex workspace and propose a project and skill management plan.

Codex will:

1. Inspect the environment in read-only mode.
2. Resolve or recommend the global AGENTS.md path, user skills root, and future-projects root.
3. Inventory existing skills without changing them.
4. Show the proposed rules, categories, optional skill relocations, and resulting structure.
5. Attach a plan ID to the proposal.
6. Wait for explicit approval before any write outside this repository.

Opening or cloning the repository is never treated as approval.

Shipped skills

Skill	Purpose
bootstrap-codex-workspace	Inspect the environment and produce an approval-bound setup plan
organize-codex-projects	Choose placement and structure for future projects
manage-codex-skills	Inventory, classify, route, catalog, and validate skills
maintain-project-ai-records	Keep lightweight project rules and milestone records
reflect-codex-workflows	Compare project evidence with existing skills before promotion

License

MIT