Skill Maintainer

Keep Agent Skills correct while the code around them changes.

Skill Maintainer detects which Skill claims are affected by a Git change, explains why, and identifies the right next action: update the Skill, repair the implementation, review an ambiguity, refresh a mapping, or do nothing.

It maps concrete Skill claims to verified files, symbols, routes, configuration, schemas, commands, and tests. Normal checks compare Git diffs with that committed local graph—without putting an LLM in CI.

Open the standalone architecture diagram.

Install

Requires Node.js 20 or newer. Skill Maintainer has two parts:

• a deterministic CLI installed in each repository;
• a plugin containing the setup and maintenance Agent Skills, installed once in each coding agent you use.

1. Install the CLI

Run this in the repository you want to maintain:

npm install --save-dev skill-maintainer

The CLI inventories the repository, validates mappings, compares Git revisions, previews safe fixes, generates reports, and runs diagnostics locally. It makes no model-provider calls.

2. Install the Agent Skills

Codex

Run these commands in your terminal:

codex plugin marketplace add ItamarZand88/skill-maintainer
codex plugin add skill-maintainer@skill-maintainer

Codex refreshes configured Git marketplaces at startup. To fetch an update immediately, run codex plugin marketplace upgrade skill-maintainer, then start a new task.

Claude Code

Run these commands inside Claude Code one at a time. First add the marketplace:

/plugin marketplace add ItamarZand88/skill-maintainer

Wait for it to finish, then install the plugin:

/plugin install skill-maintainer@skill-maintainer

Run /reload-plugins when prompted. Third-party marketplaces do not auto-update by default: run /plugin, open Marketplaces, select skill-maintainer, and choose Enable auto-update if you want updates after startup.

3. Set up the repository

After installing both parts, ask your coding agent:

Set up Skill Maintainer for this repository

For explicit invocation:

# Codex
$skill-maintainer-setup Set up Skill Maintainer for this repository.

# Claude Code
/skill-maintainer:skill-maintainer-setup Set up Skill Maintainer for this repository.

The setup Skill owns the whole onboarding flow. It discovers repository Skills, groups them by how strongly their truth depends on this repository, and asks which coverage you want:

• Strongly recommended — concrete code, workflows, contracts, schemas, commands, architecture, deployment, or authorization.
• Recommended selectively — quality, security, testing, writing, or design standards the team may adopt as project policy.
• Optional — reusable tools or external knowledge with no proven repository dependency.
• Not suitable for repository monitoring — personal behavior, general reasoning or writing style, and upstream/vendor truth.

Personal or global Skills detected by the active coding agent are shown separately and excluded by default; Skill Maintainer never commits their absolute machine paths. Identical repository copies are deduplicated by digest so only one canonical path is monitored; if the copies later diverge, the agent asks again. To monitor a global Skill, first adopt a reviewed, licensed copy into the repository intentionally.

The agent then asks whether to add a local pre-push check and/or a read-only GitHub pull-request check. After you answer, it performs the setup, maps only the selected Skills, validates the graph, and verifies relevant and unrelated changes. It remembers the decisions and asks again only for a newly discovered or materially reclassified Skill.

Running npm exec --offline -- skill-maintainer setup directly shows the deterministic preliminary groups, but it cannot make the semantic selection or ask host-native questions by itself. The Agent Skill reviews the groups and completes the workflow.

Other agents

The same two standard Agent Skills can be installed in Cursor, Gemini CLI, and other compatible hosts. See the manual host paths and verification steps.

Optional global CLI

Install globally only if you prefer bare skill-maintainer commands over the project-local form used throughout this README:

npm install --global skill-maintainer

The plugin is still required for Agent-guided setup and semantic review. Checks always use local repository state and never download Skills or packages during a run. See cross-agent packaging and discovery.

See the result

Open the self-contained interactive demo.

The HTML report leads with the action, then shows the supporting code change, the proposed Skill change when one is safe, and the relationship graph that explains why the Skill is connected to that code. Every finding includes a small copy button for a ready-to-use Agent prompt.

Relevant code excerpts are included by default. Large diffs are reduced to representative lines so the recommendation remains understandable without turning the report into a full code review.

Five commands

| Command | Purpose | | --- | --- | | skill-maintainer setup | Discover and group Skills, persist approved coverage/automation, then prepare mapping work | | skill-maintainer check | Report affected claims, authority direction, confidence, reason, and next action | | skill-maintainer fix | Preview only mechanically proven fixes; --apply validates again afterward | | skill-maintainer graph | Generate an offline HTML or SVG impact report from Skill → claim → evidence | | skill-maintainer doctor | Diagnose configuration, mapping, graph, schema, evidence, and compatibility problems |

Advanced automation can use skill-maintainer advanced prepare|validate|apply|refresh|review. Compatibility aliases remain available through v1 and print a deprecation notice.

Check a change

npm exec --offline -- skill-maintainer check --base main

1 Skill affected
1 SKILL UPDATES · 0 IMPLEMENTATION REPAIRS · 0 REVIEW · 0 MAPPING DIAGNOSTICS · 1 changed files

UPDATE REQUIRED
skills/auth/SKILL.md > Token creation (line 12)
Why: Git records an exact rename of mapped path src/auth/token.ts
Confidence: 94% (high)
Changed evidence: src/auth/registry-token.ts
Safe fix available: src/auth/token.ts → src/auth/registry-token.ts
Next: Update the affected Skill claim or apply the deterministic repair when offered

For a bounded semantic decision bundle:

npm exec --offline -- skill-maintainer check --base main --review --format json

Each bundle requires one outcome: a smallest unified diff, no-skill-change with exact evidence, or mapping-refresh-only. The deterministic CLI never writes guessed prose.

An exact Git rename can be previewed and then applied:

npm exec --offline -- skill-maintainer fix --base main
npm exec --offline -- skill-maintainer fix --base main --apply

For example:

-Use `src/auth/token.ts` to create the token.
+Use `src/auth/registry-token.ts` to create the token.

After applying, Skill Maintainer validates the mappings, rebuilds the graph, runs diagnostics, repeats the comparison, confirms the finding is gone, and verifies that unrelated Skill content did not change.

Generate a visual report

npm exec --offline -- skill-maintainer graph --base main --output skill-maintainer-report.html
npm exec --offline -- skill-maintainer graph --base main --format svg --output skill-maintainer-report.svg

The HTML report can search claims, files, symbols, and routes; filter by action, confidence, language, and framework; and expand the evidence behind each finding. Changed, broken, review, and unchanged states always have text labels—not color alone.

The report is self-contained: no backend, remote assets, analytics, or external runtime dependencies. Repository-controlled values are escaped and rendered as data rather than executable HTML. It may contain bounded code excerpts from the compared revisions, but never environment values or unrelated files.

Run locally, before a PR, or in GitHub

GitHub is optional. Run a private local check at any time:

npm exec --offline -- skill-maintainer check --staged
npm exec --offline -- skill-maintainer check --base origin/main --head HEAD --fail-on update

During Agent-led setup, choose the provider-neutral pre-push hook when you want earlier feedback. You can also add the opt-in Codex or Claude Code pre-PR hooks described in local hooks. A hook never changes the graph and does not replace a shared CI check.

Open the standalone running-modes diagram.

Add the pull-request check

The setup Agent can create this after you approve GitHub automation. For a repository that is already configured, scaffold it directly with:

npm exec --offline -- skill-maintainer setup --github

This creates .github/workflows/skill-maintainer.yml only when the explicit flag is present and never overwrites an existing workflow. The generated workflow uses:

- id: skill-maintainer
  uses: ItamarZand88/[email protected]
  with:
    fail-on: update
    # Optional: run only verifier argv commands approved in repository configuration
    # run-verifiers: "true"
    delivery: summary
    graph: html

The Action emits exact-line annotations and an outcome-first summary, exposes the report path for upload-artifact, and remains read-only for forks. Report-only mode posts no PR comments, so reruns do not create comment spam. Set branding: "false" to remove the small “Powered by Skill Maintainer” summary link. High-assurance repositories can pin the reviewed release commit SHA instead of @v0.2.1.

See Action inputs and trust boundaries, copy-ready workflows, and the realistic adoption fixture.

How it chooses the repair target

Skill Maintainer classifies individual claims, not whole Skills.

• A factual claim that describes repository behavior points from code to Skill. When that fact becomes stale, update the Skill.
• A normative claim that governs implementation points from Skill to code. General ambient guidance stays quiet; a bounded review relationship asks for judgment; a failed verified rule targets the implementation.
• A code change that is merely nearby or written in the same language does not create a finding.

Mapped collections also declare completeness. A new file in an exhaustive collection can require a Skill update; a partial collection requests review; an example remains silent. Derived content, bundled resources, runtime requirements, external sources, other Skills, and empirical data have distinct relationships and repair targets.

Open the standalone decision-flow diagram or read the directional claim model.

Evidence and trust

Skill Maintainer rejects mappings that merely say “TypeScript”, “React”, src/**, or “this file appears related.” Language, framework, import adjacency, and Git co-change may guide discovery, but they cannot independently create an impact edge. Broad scopes require an exact supporting file, symbol, route, configuration key, schema, command, or test.

Agent confidence is not authority. Hallucinated paths and values fail validation; low-confidence advisory claims are omitted from the trusted graph; unresolved ambiguity must be resolved or excluded. doctor reports these decisions with stable diagnostic codes.

.skill-maintainer/
├── config.json             human-owned policy and overrides
├── inventory.json          deterministic repository facts
├── maps/<stable-id>.json   validated claim relationships
└── graph.lock.json         compiled trusted graph; never Agent-authored

config.json also records the onboarding decision for every discovered repository Skill—selected or excluded—plus the approved local/GitHub automation modes. It stores repository-relative paths and digests only; personal/global Skill locations are never committed.

Open the standalone trust-pipeline diagram.

Skills, diffs, repository files, proposals, and Git metadata are untrusted data. Skill Maintainer does not execute commands found in them, follow symlinks outside the repository, interpolate refs into a shell, expose environment values, or send repository data to a hosted service.

Optional governance verifiers are maintainer-owned argv arrays in .skill-maintainer/config.json. They use no shell and run only after explicit --run-verifiers or run-verifiers: "true" opt-in. Base/head comparisons load verifier definitions from the base revision, so a PR cannot replace the approved command. Like any test command, a verifier executes checked-out repository code and should follow the repository's normal CI trust policy.

Verification and limitations

The included synthetic benchmark and evaluation are reproducible with:

npm run benchmark
npm run evaluate

One local verification run inventoried 2,000 synthetic files in 314 ms (6,371 files/second). The 10-case synthetic evaluation reported precision 1.0, recall 1.0, and a false-update-required rate of 0. These fixtures verify deterministic behavior; they are not a claim about every real repository.

Initial semantic mapping is only as good as the coding agent's bounded investigation and the maintainer's decisions. The adapters extract reliable repository facts, but they are not full compilers or language servers. Natural-language claims may require a focused question when multiple implementations remain genuinely plausible. Public-PR replay requires network access; normal checks and report generation do not.

For implementation details, see validation, cross-agent compatibility, graph behavior, architecture decisions, security policy, and CONTRIBUTING.md. Skill Maintainer is MIT licensed.