codex-project-skill-manager

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

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:

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

License

MIT