# skill-graph-init

> Generate a skill map

- Author: francis
- Repository: francisgreenleaf/codex-skill-graph
- Version: 20260125113001
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/francisgreenleaf/codex-skill-graph
- Web: https://mule.run/skillshub/@@francisgreenleaf/codex-skill-graph~skill-graph-init:20260125113001

---

---
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: <string>                  # required
id: <string>                    # default: name
scope: org | domain | repo       # default: repo
intent: [<string>]              # default: []
inputs: [<string>]              # default: []
outputs: [<string>]             # default: []
permissions: [<string>]         # default: []
depends_on:                     # default: {hard: [], soft: []}
  hard: [<skill-id>]
  soft: [<skill-id>]
promotion: {}                   # default: {}
description: <string>           # 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": "<ISO-8601 timestamp>",
  "skills": [
    {
      "id": "<string>",
      "name": "<string>",
      "scope": "<string>",
      "intent": ["<string>"],
      "inputs": ["<string>"],
      "outputs": ["<string>"],
      "permissions": ["<string>"],
      "depends_on": {
        "hard": ["<skill-id>"],
        "soft": ["<skill-id>"]
      },
      "promotion": {},
      "description": "<string>"
    }
  ]
}
```

`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
```