Skill Graph

Local TypeScript app for browsing Codex-style skills that already have graph metadata and for guiding graph generation for older skills.

Requirements

• Node 20+
• npm 10+
• Python 3.9+ for the bundled skill-graph-generator script

Start

npm install
npm run dev

The app starts a Fastify API and a Vite frontend. Open the local URL printed by Vite.

The API is intended for local use and binds to 127.0.0.1 by default.

For contributor-oriented setup, scripts, and project structure notes, see docs/development.md.

What This Repo Contains

• apps/web: browser UI with directory picker, graph canvas, previews, and brief generation
• apps/server: local API for scanning skills, loading graphs, previews, and copyable briefs
• packages/core: shared schema, validation, status detection, and brief helpers
• skills/skill-graph-generator: bundled standalone skill-graph-generator skill
• sample-skills: sample data for local testing

Repository notes

• sample-skills/risky-skill is an inspection-only fixture. It intentionally contains risky command patterns for review demos and should not be executed.
• The local API is a developer tool, not a multi-user service. Keep it bound to localhost unless you are deliberately testing a different deployment model.

Canonical Graph Schema

The app and generator use a single action-flow schema:

• version: "2.0"
• flow.nodes
• flow.edges

Graph metadata is action-oriented. Primary canvas nodes represent steps, decisions, parallel blocks, joins, tool calls, script runs, references, outputs, starts, and ends. Files and URLs are modeled as node attachments instead of primary graph nodes.

Skill Workflow

• Skills with agents/skill-graph.json load directly into the canvas.
• Skills without graph metadata are shown as Graph Missing.
• The app generates copyable prompts and edit briefs that assume agents/skill-graph.json can be regenerated with $skill-graph-generator.

Bundled Generator Skill

The repository includes a complete skill-graph-generator skill at skills/skill-graph-generator.

• Use the directory as a normal Codex skill by copying or symlinking it into your local skills directory.
• Or run the bundled generator script directly from this repository.

Generate Graph Metadata

You can generate graph metadata for a skill with the bundled generator skill or with a local installed copy of skill-graph-generator.

Example:

python3 skills/skill-graph-generator/scripts/generate_skill_graph.py /path/to/skill --force

This writes:

/path/to/skill/agents/skill-graph.json

Shortest Local Flow

1. npm install
2. npm run dev
3. Open the local Vite URL
4. Load sample-skills
5. Open basic-skill to inspect the bundled 2.0 action-flow graph

Common Commands

npm run dev
npm run dev:web
npm run dev:server
npm run dev:core
npm run check

Local Workspace Selection

The app does not assume a machine-specific skills directory. Pick a local workspace from the UI, or paste a local path into the command bar.

License

The repository root is licensed under MIT.

The bundled skill-graph-generator skill keeps its own Apache 2.0 license at skills/skill-graph-generator/LICENSE.