--- name: skill-graph-init id: skill-graph-init scope: org intent: - documentation - architecture-visualization inputs: - repo root path - skills root path (optional, must be inside repo) outputs: - .codex\/skill-graph\/index.html - .codex\/skill-graph\/skills.json permissions: - read_repo - write_skill_graph depends_on: hard: [] soft: [] promotion: eligible: true target_scope: org description: Generate a skill map --- # Skill Graph Init ## Overview Generate a **read-only**, static skill listing in `.codex\/skill-graph\/` by parsing YAML front-matter in each `SKILL.md` under `.codex\/skills\/`. The output is informational only and does not affect Codex behavior. ## Workflow 1) Validate preconditions - Confirm `.codex\/skills\/` exists and contains `SKILL.md` files. - If `--skills-root` is provided, validate that directory instead, but only if it is inside the repo. - If missing, fail safely with a clear message and do not write any files. 2) Extract and normalize skill metadata - Parse YAML front-matter from each `SKILL.md`. - Apply backwards-compatible defaults (see below). - Validate required fields and dependencies. 3) Generate outputs - Write `.codex\/skill-graph\/skills.json` (deterministic, sorted by `id`). - Write `.codex\/skill-graph\/index.html` plus `style.css` + `graph.js` for the graph UI. 4) Completion output - Explain where the files were written and provide a macOS command the user can run to open `index.html` locally (use `open .codex\/skill-graph\/index.html`; optionally mention `xdg-open` as an alternative for non-macOS). ## Explicit Non-Goals (Hard Constraints) - Do not edit any `SKILL.md` files. - Do not modify `.codex\/skills\/`. - Do not change Codex skill discovery or execution behavior. - Do not add any network requests or build steps. ## Filesystem Scope & Permissions - **Allowed writes (ONLY):** `.codex\/skill-graph\/` - **Forbidden writes:** `.codex\/skills\/` and any other paths ## Skill Metadata Requirements (Backwards Compatible) Only `name` is required. Defaults are applied when missing: ```yaml --- name: # required id: # default: name scope: org | domain | repo # default: repo intent: [] # default: [] inputs: [] # default: [] outputs: [] # default: [] permissions: [] # default: [] depends_on: # default: {hard: [], soft: []} hard: [] soft: [] promotion: {} # default: {} description: # optional --- ``` ## Validation Rules - `scope` is one of: `org`, `domain`, `repo`. - `intent` is a list. - `depends_on` is a mapping with `hard` and `soft` lists. - Dependency references resolve to known skill IDs. - Skill IDs are unique. If validation fails, exit with clear errors and do not produce partial output. ## Outputs `skills.json` includes all normalized fields plus `description` (empty string if missing): ```json { "generated_at": "", "skills": [ { "id": "", "name": "", "scope": "", "intent": [""], "inputs": [""], "outputs": [""], "permissions": [""], "depends_on": { "hard": [""], "soft": [""] }, "promotion": {}, "description": "" } ] } ``` `index.html` is a static graph view that shows: - Name (id) - Scope - Intent - Permissions - Description (tooltip) It must include the visible disclaimer: ``` Informational only. This does not affect Codex behavior. ``` ## Scripts Use `skill-graph-init\/scripts\/init_skill_graph.py` to generate the output safely: ```bash python3 skill-graph-init\/scripts\/init_skill_graph.py --repo-root . ``` If skills live elsewhere inside the repo, point at them explicitly: ```bash python3 skill-graph-init\/scripts\/init_skill_graph.py --repo-root . --skills-root .\/path\/to\/skills ```