The canonical home for structured SKILL.md libraries. Skill spec, JSON schemas, lint, manifest compiler, router, drift sentinel, audit loop, and the export pipeline — all shipped as a single CLI.
A plain SKILL.md gives an agent a procedure to load. The Skill Metadata Protocol adds the structured frontmatter contract. Skill Graph turns those declarations into a compiled manifest, routing map, drift sentinel, overlap detector, audit loop, and export path back to the plain SKILL.md format.
Yes, if you have more than ~5 skills that have started to depend on, verify, or exclude one another; you want deterministic checks for skill correctness (schema, paths, eval health) rather than only LLM-as-grader; you want a single audit loop that reports the Integrity Gate separately from the Behavior Gate via per-skill Health Block fields (structural_verdict, truth_verdict, comprehension_verdict, application_verdict, eval_score, drift_status); or you want graph queries over the library ("what depends on this?", "what's the boundary between X and Y?", "which skills verify this one?").
No, if you have 1–3 skills and a plain folder is enough; you want a hosted skill marketplace (Smithery, agentskills.io); you want an agent runtime (Claude Code, Cursor, Codex); or you want a tool-execution platform (Composio, your runtime's tool layer).
Full positioning vs. MCP, A2A, Anthropic Skills, Smithery, and Composio: docs/positioning.md.
The mechanism is a Karpathy-style keep-or-revert audit loop (autoresearch) applied to skill libraries instead of training scripts:
- One field, one commit, one keep-or-revert decision.
- Every change has a hard pass/fail gate — a deterministic check script that turns red or green.
- Failed changes auto-revert. The lesson is recorded; the field's truth is preserved.
The protocol's typed fields are the substrate that makes deterministic gates possible. The audit loop (SKILL_AUDIT_LOOP.md) is the mechanism. The quality bar that governs every change — what "improve" means, when it's safe to remove, how to enrich without dropping coverage — is codified in docs/quality-doctrine.md. Together they produce a library that drifts less, even as it grows.
%%{init: {'theme':'neutral','flowchart':{'curve':'basis','padding':20}}}%%
graph TD
G["<b>skill-graph</b><br/><i>canonical monolith: spec, schemas, tooling, audit</i><br/>@skill-graph/cli — npm install -g"]
L["<b>skills</b><br/><i>public open-source skill library</i><br/>npx skills add jacob-balslev/skills"]
P["<b>skill-metadata-protocol</b><br/><i>deprecated · docs-only mirror</i><br/>SKILL_METADATA_PROTOCOL.md preserved"]
A["<b>skill-audit-loop</b><br/><i>deprecated · docs-only mirror</i><br/>SKILL_AUDIT_LOOP.md preserved"]
G -->|exports SKILL.md| L
G -. mirrors protocol spec to .-> P
G -. mirrors audit procedure to .-> A
classDef active fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
classDef tool fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f;
classDef mirror fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,color:#4b5563,stroke-dasharray:4 3;
class G tool;
class L active;
class P,A mirror;
| Repo | npm | Status | Purpose |
|---|---|---|---|
| skill-graph (this repo) | @skill-graph/cli |
active | Canonical home — protocol spec, schemas, CLI, lint, manifest, router, drift, audit loop, export |
| skills | — | active | Public open-source skill library (consumed via npx skills add jacob-balslev/skills) |
| skill-metadata-protocol | (consolidated) | mirror | Historical docs-only mirror of the normative spec — content lives here |
| skill-audit-loop | (consolidated) | mirror | Historical docs-only mirror of the audit procedure — content lives here |
Recent consolidation (2026-05-18): Per SH-6137 and ADR 0009,
@skill-graph/protocoland@skill-graph/auditwere merged into@skill-graph/cli@0.5.6. Schemas, audit scripts, graders, eval fixtures, examples, and the protocol/audit canonical docs now all live in this repo. The sibling repos are preserved as read-only mirrors so existing inbound links remain valid; they were archived on GitHub on 2026-05-20 (read-only, still publicly readable — see ADR 0009 § Update).
Two onboarding paths, by need:
- "I want to author my first skill in 30 minutes." →
docs/QUICKSTART-30MIN.md— literal terminal walkthrough: clone, install, fill in the template, lint, route a query, record the drift baseline. Use this when you'd rather try the tooling than read about it. - "I want to understand the model before I commit." →
docs/PRIMER.md— conceptual primer: what the protocol is, when to adopt it, the four orthogonal classification axes, the routing model, and what Skill Graph is not. Use this when you'd rather build the mental model first.
The QUICKSTART points at the PRIMER for the "why"; the PRIMER points at the QUICKSTART for the "how". Read either first, then loop back.
For everything else:
| If you want to… | Start here |
|---|---|
| Install the CLI | Quick Start below — npm install -g @skill-graph/cli |
| Install the public skill library | jacob-balslev/skills — npx skills add jacob-balslev/skills |
Understand the SKILL.md frontmatter contract |
SKILL_METADATA_PROTOCOL.md — the normative spec |
| Audit an existing skill library | SKILL_AUDIT_LOOP.md — the audit procedure |
| Look up a specific field | docs/field-reference.md |
| Plan adoption in a new repo | docs/ADOPTION.md and docs/CONFORMANCE.md |
Migrate from an older schema_version |
git history (per ADR 0014) |
Surface scope: The OSS-portable canonical library lives at
skills/skills/; the live count is the single-source-of-truth value inSKILL_GRAPH.md § Current State(per the AGENTS.md Doc Ownership Map — every other doc links rather than inlining). A separate personal/Sales Hub surface atskills/is frozen — new skills are curated into the OSS surface only when non-PII, non-Sales-Hub, and generalizable. See ADR 0008.
| Layer | Job | Concrete output |
|---|---|---|
| SKILL.md format | Portable skill packaging. | A folder with SKILL.md, optional scripts/, references/, and assets/. |
| Skill Metadata Protocol | The per-skill relevance contract. | YAML frontmatter that declares identity, scope, taxonomy, activation signals, relations, grounding, eval state, and portability. |
| Skill Graph | The library-level system around the protocol. | Lint, manifest generation, routing, clustering, overlap checks, drift checks, audits, evals, and SKILL.md export. |
The distinction matters. The SKILL.md format answers "what can this skill do?" Skill Metadata Protocol answers "what is this skill relevant for, where does it belong, and what makes it trustworthy?" Skill Graph answers "how do we operate across a whole library of those declarations?"
The plain SKILL.md format only needs name and description for the smallest useful skill. That is enough for small libraries. It breaks down when a project has many skills, overlapping domains, multiple workspaces, stale codebase assumptions, or a team that needs to audit why a skill was loaded.
Skill Metadata Protocol makes these questions explicit:
| Question | Protocol fields |
|---|---|
| What kind of skill is this? | type, scope, version, owner |
| Where does it belong? | category, domain, workspace_tags, routing_bundles |
| When should it load? | description, keywords, triggers, examples, anti_examples, paths |
| What is it near, dependent on, or not responsible for? | relations.related, relations.depends_on, relations.verify_with, relations.boundary, relations.broader, relations.narrower |
| What evidence makes it true? | grounding.truth_sources, grounding.failure_modes, grounding.evidence_priority |
| Is it current and tested? | freshness, drift_check, eval_artifacts, eval_state, routing_eval, eval_last_run, lifecycle |
| Can it move to another runtime? | portability, compatibility, allowed-tools |
Once those fields exist, a skill library stops being a flat folder of Markdown files. It becomes a map of project knowledge that humans can browse and agents can route through.
This is a compact example. The full authoring scaffold is examples/skill-metadata-template.md.
---
schema_version: 7
name: product-page-ux-review
description: "Use when reviewing a product page's UX, visual hierarchy, interaction patterns, accessibility, and conversion-critical content. Do NOT use for backend Shopify API work, production incident debugging, or general copy editing outside the product-page experience."
version: 1.0.0
# v7 axes (still globally required by the schema)
type: capability
category: design
domain: design/ux
scope: project
# v8 axes (additionally required when schema_version: 8 — author both during sunset)
subject: design-craft
operation: decide
owner: design-platform
freshness: "2026-05-13"
drift_check:
last_verified: "2026-05-13"
eval_artifacts: planned
eval_state: unverified
routing_eval: absent
keywords:
- product page UX
- visual hierarchy
- Shopify product detail page
- conversion friction
- dark mode review
examples:
- "Review this Shopify product page for UX problems before launch."
- "Map which design skills should be loaded for a dark-mode PDP redesign."
anti_examples:
- "Fix the Shopify webhook signature validation failure."
- "Diagnose why the checkout build failed in CI."
workspace_tags:
- ecommerce
- shopify
- frontend
routing_bundles:
- product-experience
paths:
- app/products/**/*
- components/product/**/*
relations:
related:
- visual-hierarchy
- color-system-design
- typography-system
- dark-mode-implementation
boundary:
- skill: shopify
reason: "shopify owns API, integration, and platform behavior; this skill owns product-page UX review"
- skill: debugging
reason: "debugging owns concrete runtime failures; this skill owns pre-release design review"
verify_with:
- a11y
- usability-testing
grounding:
domain_object: Shopify product page UX surface
grounding_mode: repo_specific
truth_sources:
- path: app/products/[handle]/page.tsx
- path: components/product/ProductGallery.tsx
failure_modes:
- visual_hierarchy_unclear
- color_contrast_regression
- interaction_feedback_missing
evidence_priority: repo_code_first
portability:
readiness: scripted
targets:
- skill-md
lifecycle:
stale_after_days: 90
review_cadence: quarterly
---The protocol is the contract. The template is just the easiest way to author the contract correctly.
Skill Metadata Protocol uses several independent axes. They should not be collapsed into one taxonomy.
| Axis | Field | Cardinality | Use |
|---|---|---|---|
| Archetype | type |
one | Skill shape: capability, workflow, router, or overlay. |
| Scope | scope |
one | Where it applies: portable, workspace, or project (with reference/codebase accepted as v7 aliases during sunset). |
| Top-level category | category |
one | Flat top-level shelf for browsing. |
| Domain path | domain |
zero or one | Slash-delimited hierarchy, such as design/ux or architecture/events. |
| Project group | workspace_tags |
many | Which project families, workspaces, or product areas this skill applies to. |
| Routing group | routing_bundles |
many | Runtime bundles or dispatch groups. |
| Relations | relations.* |
many | Typed graph edges between skills. |
| Grounding | grounding.* |
conditional | Truth sources and failure modes for repo-grounded skills. |
The schema uses category for the flat top-level shelf and domain for the hierarchical path. category is the closed enum above; adopters choose their own domain, workspace_tags, and routing_bundles values. The canonical sibling library (~/Development/skills/) and the examples/ specimens currently demonstrate the following domain / group values.
category is a closed enum of six (since schema v5, current in v7), enforced by the schema and scripts/lint/check-category-enum.js:
foundations, engineering, design, quality, agent, product
These are the values used across the canonical skill library (the sibling ~/Development/skills/ repo, nested <category>/<name>/) and the examples/fixture-skills/ specimens. Cross-cutting fit is expressed via relations.related, never by adding a category value.
| Domain root | Current domain paths |
|---|---|
ai-engineering |
ai-engineering/analysis, ai-engineering/architecture, ai-engineering/concepts, ai-engineering/context, ai-engineering/evaluation, ai-engineering/knowledge, ai-engineering/knowledge-extraction, ai-engineering/knowledge-representation, ai-engineering/language, ai-engineering/prompts, ai-engineering/safety, ai-engineering/strategy, ai-engineering/tool-use |
architecture |
architecture/contracts, architecture/decision-records, architecture/dependencies, architecture/domain-boundaries, architecture/domain-discovery, architecture/events, architecture/technology-selection |
content |
content/build/images, content/maintenance, content/markdown/frontmatter, content/migrations, content/routing |
data |
data/migrations, data/modeling |
design |
design/information-architecture, design/interaction, design/ux, design/visual |
engineering |
engineering/api-design, engineering/debugging, engineering/observability, engineering/performance, engineering/quality, engineering/version-control |
frontend |
frontend/design-system, frontend/layout |
integrations |
integrations/webhooks |
modeling |
modeling/conceptual, modeling/ontology, modeling/state-machines, modeling/taxonomy |
skill-system |
skill-system/authoring, skill-system/health |
workspace_tags demonstrated in this repo:
build-pipeline, content, markdown, migrations, skill-authoring, static-site
routing_bundles demonstrated in this repo:
quality
Downstream projects should add their own tags: shopify, checkout, billing, design-system, docs-site, mobile, b2b-saas, healthcare, and so on. Tags are not a global ontology. They are routing and maintenance handles for your workspace.
The main payoff is not the YAML. The payoff is that a project can load the right cluster of skills for a real task.
Triangulation means selecting skills from multiple independent signals:
| Signal | Example |
|---|---|
| Project surface | workspace_tags: [shopify, frontend], paths: components/product/**/* |
| Top-level and domain category | category: design, domain: design/ux |
| Method or phase | design-thinking, user-research, ideation, prototyping, usability-testing |
| Related skills | visual-hierarchy, color-system-design, typography-system, dark-mode-implementation |
| Verification skills | a11y, testing-strategy, code-review |
| Negative boundaries | shopify for API work, debugging for runtime failures |
For a UX designer working on a Shopify product page, Skill Graph can form a cluster like this:
| Design phase | Skills to load |
|---|---|
| Empathize | user-research, task-analysis, journey-mapping |
| Define | problem-framing, information-architecture, research-synthesis |
| Ideate | ideation, visual-design-foundations, interaction-patterns |
| Prototype | prototyping, layout-composition, design-module-composition, color-system-design, typography-system, dark-mode-implementation |
| Test | usability-testing, a11y, interaction-feedback |
| Project-specific context | shopify, frontend-architecture, design-system-architecture |
That is the difference between asking an agent to "use the UX skill" and giving it a structured project map: what area is being changed, which design phase the work is in, which sibling skills should co-load, and which nearby skills should not take over.
A skill is a contract about a subject. The contract is inert on its own — it stays useful only while the things it was written against still hold. Two of those things move: the codebase the skill is grounded in, and the subject the skill describes. The Skill Audit Loop re-grounds a skill against both. It is what keeps a skill true to its declared grounding.truth_sources once time has passed — whether a maintainer runs it across a whole library or an adopter runs it against their own repo.
The loop adapts two useful patterns:
- From Karpathy's
autoresearch: a tight loop with a constrained action surface, a fixed experiment, a measurable result, and keep-or-revert pressure. - From Stanford d.school design thinking and IDEO's design thinking framing: human-centered iteration through discovery, framing, ideation, prototyping, testing, and loop-back when evidence changes the problem.
For skills, the loop is:
- Pick a skill or project area.
- Gather evidence: the
SKILL.md, eval files, manifest entry, related skills, andgrounding.truth_sources. - Run the Integrity Gate first: schema lint, relation integrity, manifest validation, routing assertions, overlap checks, export checks, and drift checks.
- Run the Behavior Gate when certification is needed: realistic positive evals, hard negatives, prior failure regressions, and boundary cases that show whether the skill changes agent behavior.
- Fix the skill or its metadata when the evidence supports the change.
- Re-run checks and record the new state.
- Move to the next skill or loop back if the fix changed the graph.
This is not "self-improving skills" as a slogan. It is a re-grounding loop with evidence, constraints, and repeatable checks. The Integrity Gate proves the skill is safe for the graph; the Behavior Gate proves the skill is useful to an agent.
The public, ready-to-install skill library lives at jacob-balslev/skills — install with:
npx skills add jacob-balslev/skillsThat repo holds the canonical skill library in plain Agent-Skills shape (live count in SKILL_GRAPH.md § Current State), indexed on skills.sh. You do not need to clone this skill-graph tooling repo to consume the skills.
Install the CLI from npm:
npm install --global @skill-graph/cli
skill-graph --helpOr skip install entirely and open the repo in a pre-configured GitHub Codespace — Node 20, skill-graph linked globally, doctor smoke-run on first boot, suggested next commands shown on attach:
The devcontainer lives at .devcontainer/devcontainer.json; first-boot logic is in .devcontainer/post-create.sh.
The tooling operates against a skill library configured via .skill-graph/config.json → workspace.skill_roots. Post-2026-05-18 consolidation, the shipped config points at the public jacob-balslev/skills repo — the canonical skill library, with the live count in SKILL_GRAPH.md § Current State. Clone the canonical skills as a sibling of this repo and the tooling resolves automatically — no env-vars needed:
git clone https://github.com/jacob-balslev/skills.git ~/Development/skills
cd ~/Development/skill-graph # this repo (tooling)
# Validate every skill against the schema and lint rules.
node scripts/skill-lint.js
# Route a real request and print why each skill was selected, co-loaded, or excluded.
node scripts/skill-graph-route.js "audit my skills for schema conformance"
# Check grounded skills against recorded truth-source hashes.
node scripts/skill-graph-drift.jsIf your layout differs from the canonical-sibling assumption (e.g., canonical skills cloned elsewhere), override via the SKILL_GRAPH_WORKSPACE env-var or edit .skill-graph/config.json to point workspace.skill_roots at your skill directory.
To regenerate the plain public marketplace staging surface from the canonical source:
node scripts/export-marketplace-skills.js
node scripts/export-marketplace-skills.js --check
node scripts/verify-skill-md-export.js --plain marketplace/skillsThe staging surface lands under marketplace/ for the two-step sync into jacob-balslev/skills (see AGENTS.MD § Release sync). The canonical end-user install path is npx skills add jacob-balslev/skills — that is the path consumers see, and it must remain working before any marketplace badge is added.
The npm package exposes the same scripts through a skill-graph binary:
skill-graph init my-skill # Scaffold a new SKILL.md from the template
skill-graph add debugging # Install a skill from the marketplace
skill-graph lint # Validate all SKILL.md files
skill-graph audit my-skill # Seed or run a single-skill audit
skill-graph route "schema drift" # Select skills for a query
skill-graph drift # Check truth-source hashes
skill-graph eval-staleness # Check eval file/path/symbol claims
skill-graph export # Generate marketplace export surface
skill-graph evolve --top 5 # PREVIEW: continuous improvement loop (standalone; see Standalone Installation section)Run skill-graph --help to see all commands (including legacy aliases).
All subcommands except evolve work standalone out of the box after npm install -g @skill-graph/cli. The cross-repo path escapes in the audit and evolve pipeline were removed in SH-6138; the package no longer requires the Development monorepo to be present.
npm install -g @skill-graph/cli
# Point the CLI at your skill library — one of three ways:
# 1. cd into your workspace (the CLI defaults SKILL_GRAPH_WORKSPACE to cwd)
cd /path/to/my-skills && skill-graph lint
# 2. Set SKILL_GRAPH_WORKSPACE explicitly
SKILL_GRAPH_WORKSPACE=/path/to/my-skills skill-graph audit my-skill
# 3. Add a .skill-graph/config.json to your workspace to configure skill_roots| Command | Standalone flag | Purpose |
|---|---|---|
skill-graph audit <skill> |
--dry-run |
Resolve skill and run lint without writing any files. Useful for smoke-testing a fresh install. |
skill-graph audit <skill> |
--audit-root <path> |
Write audit artifacts to a custom directory instead of <workspace>/audits/. |
skill-graph evolve |
--workspace-root <path> |
Root of your skills workspace (defaults to cwd). |
skill-graph evolve |
--skills-dir <path> |
Directory containing your SKILL.md files (defaults to <workspace-root>/skills). |
skill-graph evolve |
--output-dir <path> |
Directory for evolve output artifacts (defaults to <workspace-root>/audits). |
| All commands | SKILL_GRAPH_WORKSPACE env var |
Override workspace root globally — useful in CI pipelines or when your skill library is not in cwd. |
# Install the CLI globally
npm install -g @skill-graph/cli
# Verify the audit pipeline resolves your skill without writing files (exit 0 = healthy)
skill-graph audit <your-skill-name> --dry-run
# Verify the evolve pipeline prints its help and exit codes
skill-graph evolve --helpskill-graph evolve ships bundled with lib/audit-shared/auto-improve.js (included in the package). For standalone use, pass the required workspace flags:
skill-graph evolve \
--workspace-root /path/to/my-skills \
--skills-dir /path/to/my-skills/skills \
--output-dir /path/to/my-skills/audits \
--top 5 --max-cycles 3Exit codes for skill-graph evolve:
| Code | Meaning |
|---|---|
0 |
Loop completed successfully (or --analyze-only finished). |
1 |
Fatal error (missing required dependency, unresolvable skill root, etc.). |
2 |
Failure budget exceeded (--failure-budget). |
| Tool | Purpose |
|---|---|
scripts/skill-lint.js |
Canonical-source schema gate: valid frontmatter, schemas/skill.schema.json validation, identifier shape, non-empty description, and parent-directory/name alignment. Routing quality, relation existence, drift, export, and eval checks live in the dedicated tools below. |
scripts/check-protocol-consistency.js |
Cross-artifact checks so schemas, docs, generated field references, and sample manifests stay aligned. |
scripts/generate-manifest.js |
Compiles all skills into a deterministic manifest for routing and downstream tooling. |
scripts/skill-graph-route.js |
Reference router that explains selected, co-loaded, and excluded skills. |
scripts/skill-graph-routing-eval.js |
Checks examples and anti_examples against router behavior. |
scripts/skill-graph-drift.js |
Hashes grounding.truth_sources and reports drift, broken sources, stale skills, or missing baselines. |
lib/audit/eval-staleness-checker.js |
Checks examples/evals/*.json for stale file-path, line-range, and symbol claims using the configured skill roots. |
scripts/skill-overlap.js |
Finds overlapping skill ownership and routing ambiguity. |
scripts/skill-audit.js |
Generates audit artifacts and optional graded review prompts. |
scripts/export-skill.js |
Exports protocol-enriched skills back to plain SKILL.md shape. |
scripts/export-marketplace-skills.js |
Generates and validates the public plain SKILL.md marketplace surface with provenance, description-limit, privacy, and link gates. |
| Path | Purpose |
|---|---|
SKILL_GRAPH.md |
Library-level system model and authority tiers. |
SKILL_METADATA_PROTOCOL.md |
Canonical normative spec for the SKILL.md frontmatter contract. |
SKILL_AUDIT_LOOP.md |
Canonical audit procedure (4 operations: audit, improve, evaluate, evolve). |
SKILL_AUDIT_LOOP.md § Part 2 — Per-Skill Audit Checklist |
Per-skill audit checklist used during audit. |
AGENTS.md |
Agent-facing repo guide (doctrine, doc routing, validation commands, lib/ layout, public-distribution contract). CLAUDE.md imports it. |
CHANGELOG.md |
Release notes for protocol, schemas, scripts, and CLI. |
schemas/ |
Canonical-only JSON Schemas — skill.schema.json (the binding contract; schema_version: 7 currently) + manifest.schema.json + audits-manifest.schema.json + comprehension.schema.json. Prior contract versions (v2-v6) live in git history per ADR-0014. Also skill.context.jsonld and a vocabulary/ namespace. |
lib/audit/ |
Audit-loop runtime bundled in @skill-graph/cli — see AGENTS.md § Internal lib/ layout. |
marketplace/ |
Staging buffer for the public jacob-balslev/skills release. Generated by scripts/export-marketplace-skills.js. Never hand-edit — see AGENTS.md § Public Distribution. |
audits/ |
Per-skill audit artifacts (audits/<skill>/findings.md, verdict.md, scorecard.md) emitted by audit. Evidence, not state — state lives in each skill's Health Block. |
evals/ |
Routing-eval baseline (retrieval-baseline-v2.json). Per-skill comprehension/application evals live alongside each skill or under examples/evals/. |
data/ |
Hand-edited classification data feeding upstream tooling. Today: publication-classification.json (per-skill OSS publication tier, consumed by the parent Development repo's audit worklist). |
examples/skill-metadata-template.md |
Copyable authoring template. |
examples/projects/markdown-static-site/ |
Specimen project with codebase-grounded skills. |
docs/field-reference.md |
Field-by-field reference. |
docs/field-decision-guide.md |
Decision tables for hard field choices. |
docs/quality-doctrine.md |
Quality bar for preserving scope, readable names, organization-over-trimming, compression, and verification. |
docs/SKILL-MD-FORMAT-COMPATIBILITY.md |
How export maps protocol-enriched skills back to plain SKILL.md. |
docs/marketplace-syndication.md |
Syndication workflow for public SKILL.md marketplaces. |
docs/adr/ |
Architecture Decision Records, including ADR 0009 — sibling repo deprecation. |
| git history (per ADR 0014) | Per-bump author migration procedures (v4→v5, v5→v6, v6→v7). |
Related repos:
| Repo | Status | Purpose |
|---|---|---|
jacob-balslev/skills |
active | Public open-source canonical skill library — live count in SKILL_GRAPH.md § Current State. Distributed via npx skills add jacob-balslev/skills. |
jacob-balslev/skill-metadata-protocol |
mirror | Historical docs-only mirror of the protocol spec (kept for inbound-link stability). Canonical doc now in SKILL_METADATA_PROTOCOL.md. |
jacob-balslev/skill-audit-loop |
mirror | Historical docs-only mirror of the audit workflow. Canonical doc now in SKILL_AUDIT_LOOP.md. |
If you have a parent pnpm-workspace.yaml above this directory (e.g. when this repo is checked out inside the Development monorepo), pnpm will absorb skill-graph/ into the parent workspace. That blocks standalone pnpm-lock.yaml generation here. For local dev/lockfile work, run:
pnpm install --ignore-workspace
pnpm install --frozen-lockfile --ignore-workspaceCI is unaffected — .github/workflows/publish.yml runs in a clean checkout with no parent workspace, so the unflagged pnpm install --frozen-lockfile works correctly there.
Before cutting the first release, ensure these one-time steps are done:
- npm org — the
@skill-graphnpm org must exist. The npm CLI does NOT supportnpm org create; orgs are created via the website. Go to https://www.npmjs.com/org/create, enterskill-graphas the org name, pick "Unlimited public packages — Free", and add yourself as owner. Verify withnpm org ls skill-graph. - NPM_TOKEN secret — generate a publish token (
npm token create --read-only=false) and add it asNPM_TOKENin the GitHub repo secrets (Settings → Secrets and variables → Actions). For finer scoping, manage tokens at https://www.npmjs.com/settings//tokens.
# 1. Bump version, commit, and tag locally
pnpm version patch # or minor, or major
# 2. Push the commit and the tag — the tag push by itself does NOT publish
git push && git push --tags
# 3. Trigger the publish workflow manually from the GitHub Actions UI,
# or via the CLI, passing the tag you just pushed:
gh workflow run "Publish @skill-graph/cli to npm" -f tag=v0.5.9The publish pipeline at .github/workflows/publish.yml is manually gated as of v0.5.9: it triggers only on workflow_dispatch and requires the maintainer to enter the release tag. The workflow checks out that tag, runs pnpm test, then publishes @skill-graph/cli with provenance attestation. The npm package is always published from CI — do not run pnpm publish locally. (Releases up to and including v0.5.8 used an auto-publish-on-tag trigger; the manual gate was added immediately after the v0.5.8 publish completed.)
| Step | Who | Command |
|---|---|---|
Create @skill-graph npm org (once) |
Jacob | https://www.npmjs.com/org/create — pick "Unlimited public packages — Free" |
Add NPM_TOKEN GitHub secret (once) |
Jacob | GitHub Settings → Secrets |
| Cut a release | Maintainer | pnpm version <patch|minor|major> then git push --tags, then gh workflow run "Publish @skill-graph/cli to npm" -f tag=v<x.y.z> |
CLI distribution via npm (
@skill-graph/cli) is separate from skill library syndication. The skill library is published fromjacob-balslev/skillsvianpx skills add jacob-balslev/skills. Seedocs/marketplace-syndication.mdfor the skill library syndication workflow. See SH-6110 for install verification.
Skill Graph is not:
- a hosted skill marketplace
- an agent runtime
- persistent agent memory
- a replacement for
AGENTS.mdorCLAUDE.md - a prompt library
- a guarantee that every skill is correct
It is a structured protocol and reference toolchain for making skills easier to route, cluster, verify, maintain, and port.
Skill Graph sits above plain SKILL.md files and beside runtime protocols like MCP and A2A. It is an authoring + audit-time project, not a runtime. Full positioning with explicit comparisons against Anthropic Skills, the Agent Skills spec, MCP, A2A, Smithery, Composio, and AGENTS.md lives in docs/positioning.md — it names what Skill Graph is not before naming what it is.
One-line summary: most agent-skills projects answer "how does the agent find / load / call / dispatch / publish a skill?" Skill Graph answers "how do you keep a library of skills correct over time?" The unique mechanism is the Karpathy keep-or-revert audit loop applied to skill libraries instead of training scripts (see Skill Audit Loop below and docs/quality-doctrine.md for the quality bar that doctrine enforces).
For project framing context, see GitHub Discussion #1 and the linked Bluesky thread.
Latest release: @skill-graph/cli@0.5.10 (2026-05-25) — the "canonical-shape sweep" release closing the 2026-05-25 multi-model restructure review backlog. See CHANGELOG.md and the generated docs/status.generated.md. The current contract is schema_version: 7 — see schemas/skill.schema.json for the authoritative shape. Per ADR-0014 (canonical-only schema files), only schema.json lives on disk; prior contract versions (v2-v6) are recoverable from git history (git show <commit>:schemas/skill.schema.json) and external consumers pinning a historical version should resolve against a tag rather than a duplicate file. The schema's $id (https://skillgraph.dev/schemas/skill.schema.json) is the stable identifier.
- Contributing — see
CONTRIBUTING.md. Issues and PRs welcome via the structured templates in.github/. - Security — report vulnerabilities privately via the security policy, not as public issues.
- Code of Conduct — this project follows the Contributor Covenant 2.1.
- License — code is licensed under Apache-2.0. Skill content and documentation under CC-BY-4.0 where noted in
NOTICE. - Discussions — open-ended questions and ideas welcome in GitHub Discussions.