SkillWire

Repository capability infrastructure for AI coding agents.

SkillWire is a repository capability layer that maps portable engineering intent to repository-native commands, components, environments, and conventions.

Agent Skills packs distribute portable engineering workflows as Markdown. Portability is the design goal, and its cost is that a skill cannot know how any particular repository is built, tested, or checked.

SkillWire provides that layer. It discovers a repository's real commands, records the evidence behind each one, and exposes them to coding agents through static exports and a read-only MCP server.

v0.1 includes integration profiles for three workflows from addyosmani/agent-skills, complementing portable Agent Skills with repository-specific capability resolution.

How it works

A pnpm workspace where three plausible test commands exist:

package.json                      "test": "pnpm -r test"
services/orders/package.json      "test": "vitest run"
                                  "test:unit": "vitest run --config vitest.unit.ts"
.github/workflows/orders-ci.yml   pnpm --filter @acme/orders test:unit

skillwire resolve test.all --component @acme/orders --environment ci

RESOLVED — unverified

Capability: test.all
Component: @acme/orders
Environment: ci
Working directory: services/orders
Command: ["pnpm","--filter","@acme/orders","test:unit"]
Authority: active-ci-workflow

Every resolution carries its reasoning:

skillwire explain test.all --component @acme/orders --environment ci

Reason: active CI workflow .github/workflows/orders-ci.yml line 8

Evidence:
  .github/workflows/orders-ci.yml  sha256:df4951e5b6fd

Candidates:
  [selected] ["pnpm","--filter","@acme/orders","test:unit"] @ services/orders
  [rejected] ["pnpm","test"] @ services/orders
             lower authority (package-script) than selected active-ci-workflow
  [rejected] ["pnpm","test"] @ .
             belongs to component workspace-root, not requested component @acme/orders

When the CI workflow later changes test:unit to test:ci, the committed state no longer matches the repository:

skillwire check

STALE  test.all/@acme/orders/ci
       resolution changed: "pnpm --filter @acme/orders test:unit"
                        -> "pnpm --filter @acme/orders test:ci"

No repository commands were executed.

That is the core product loop:

discover → scope → resolve → explain → persist → drift

An agent can read those files itself — and get a different answer each session, with no record of why. SkillWire persists the answer: which command, for which component, in which environment, on what evidence, and whether it has ever been verified. That state is committed, so a pull request can show when a build command changes and why.

What v0.1 does

• deterministic repository discovery for Python and Node/TypeScript (uv, Poetry, npm, pnpm)
• component- and environment-aware capability resolution
• explainable provenance, authority, ambiguity, and rejected alternatives
• persistent, reviewable .skillwire/ state
• first-class project overrides
• explicit, non-isolated local verification
• static agent exports for Claude Code, Cursor, and AGENTS.md
• three addyosmani/agent-skills integration profiles
• a read-only MCP server
• non-executing drift checks for CI
• cross-platform binaries for Linux, macOS, and Windows

Benchmark status

The canonical 20-repository benchmark manifest is pinned to exact commit SHAs with reviewed expectations. No results are published yet. Accuracy and execution numbers will come only from a completed public benchmark run against those commits — this repository does not ship hand-authored result JSON. See benchmark/README.md.

Target users

Primary: engineers using AI coding agents

SkillWire is for engineers already using tools such as:

• Claude Code
• OpenAI Codex
• Cursor
• GitHub Copilot
• Gemini CLI
• another MCP-capable coding agent
• addyosmani/agent-skills or another Agent Skills pack

They want coding agents to use the correct repository commands without repeatedly exploring or guessing.

Primary job to be done:

When my coding agent needs to install dependencies, test, lint, type-check, or build a component, give it the correct repository-native operation with explicit scope and provenance.

Secondary: platform, DevEx, and engineering-productivity teams

These teams can maintain one reviewable repository capability model and expose it consistently through static instructions, MCP, and CI drift checks.

Skill-pack authors are a future ecosystem participant, not an MVP target. No v0.1 feature exists solely to make third-party authors adopt SkillWire's vocabulary.

Core capability model

v0.1 defines six semantic capabilities:

deps.install
test.all
test.focused
lint
typecheck
build

Every capability is scoped by:

capability + component + environment

The three key axes remain independent:

Axis	Values
Resolution	resolved · ambiguous · unsupported
Authority	explicit-override · active-ci-workflow · task-runner · package-script · build-configuration · documentation · convention · heuristic
Verification	unverified · verified · failed · stale

A governing invariant is:

Important

SkillWire must not convert uncertainty into a confident command.

Commands are structured vectors, never ordinary shell command strings:

{
  "executable": "uv",
  "arguments": ["run", "pytest"]
}

CI/documentation text containing compound shell syntax is retained as repository evidence but is not converted into an executable candidate.

Supported Repository surfaces

Python · Node/TypeScript · Shared Surfaces

Python

• pyproject.toml
• uv.lock / uv
• poetry.lock / Poetry
• pytest config in pyproject.toml, pytest.ini, or tox.ini
• Ruff config in pyproject.toml, ruff.toml, or .ruff.toml
• mypy config in pyproject.toml or mypy.ini
• pyright config in pyproject.toml or pyrightconfig.json
• Python build-system configuration

Node / TypeScript

• package.json
• npm / package-lock.json
• pnpm / pnpm-lock.yaml
• pnpm-workspace.yaml
• Jest / Vitest
• ESLint
• TypeScript / tsconfig.json
• package build scripts

Shared

• GitHub Actions workflows
• Makefile
• Taskfile.yml / Taskfile.yaml
• justfile
• explicit $ command lines in AGENTS.md and CLAUDE.md
• single projects, basic monorepos, pnpm workspaces, and mixed Python/Node repositories

Structured configuration is parsed deterministically. SkillWire does not require an LLM to analyze a repository.

Resolution precedence

SkillWire ranks candidates in this order:

1. explicit SkillWire override
2. active CI workflow
3. checked-in wrapper or task runner
4. package/build configuration
5. repository documentation
6. framework/tool convention
7. heuristic inference

If equally authoritative candidates remain after component and environment scoping, SkillWire returns ambiguous instead of choosing one arbitrarily.

Committed capabilities.lock.json files use a normalized, component-grouped representation: unsupported tuples and resolved-candidate diagnostics are recomputed rather than repeated, common component paths/evidence are stored once, and legacy array-form locks remain readable. skillwire explain (and MCP explain_capability) reconstructs detailed live candidates when needed, keeping command-change diffs reviewable even in large monorepos.

Quick start

Requires Go 1.23+.

Install SkillWire:

go install github.com/ygmrs/skillwire/cmd/skillwire@latest

Inspect a repository without modifying it:

skillwire inspect --root /path/to/repo

Initialize persistent state and query the repository:

cd /path/to/repo
skillwire init

skillwire components
skillwire resolve test.all --component <id>
skillwire explain test.all --component <id> --environment ci

Commit .skillwire/, then check for drift in CI. This executes no repository commands:

skillwire check

Persistent project state

skillwire init creates:

.skillwire/
├── skillwire.yaml
├── overrides.yaml
├── capabilities.lock.json
├── profiles.lock.json
├── runs/                     # ignored local verification output
└── cache/                    # ignored local cache

The important contract is that capabilities.lock.json is generated and committed. It records the selected capability state and evidence fingerprints so a PR can answer: “why did this test command change?”

Command boundaries are deliberate:

Command	Behavior
skillwire init	first setup + first committed lock
skillwire inspect	analyze and report; write nothing
skillwire refresh	accept current resolution state into the lock; execute nothing
skillwire check	compare committed state to current evidence; execute nothing by default

Lock serialization is deterministic and component-grouped, with entries canonically ordered by capability/environment and shared evidence normalized once.

Overrides

Correct an automatic resolution without editing generated JSON:

skillwire override set test.all \
  --component orders-api \
  --environment local \
  --cwd services/orders-api \
  -- uv run pytest -c config/pytest.ini

Other commands:

skillwire override list
skillwire override show test.all --component orders-api
skillwire override remove test.all --component orders-api
skillwire override verify test.all --component orders-api

An override becomes the highest resolution authority, but it remains unverified until explicitly executed. After changing overrides, run skillwire refresh to update the committed lock.

Verification security boundary

Warning

SkillWire local verification executes repository-defined commands on your machine as your current user. The local backend is controlled but NOT ISOLATED.

Repository commands may read or modify files, start processes, use available host resources, access the network, or trigger package lifecycle scripts. Filtering child environment variables and avoiding a shell do not sandbox repository code. Verification timeouts also bound the extra wait for inherited output pipes. Captured stdout and stderr are each capped at 1 MiB with explicit truncation/total-byte metadata. The local backend does not guarantee process-tree cleanup; descendants may outlive the direct command.

Verification defaults to local:

skillwire verify test.all --component orders-api

CI-scoped commands may depend on runner-only environment, prior steps, services, generated files, or credentials. Noninteractive CI verification therefore requires explicit acknowledgement:

skillwire verify test.all \
  --component orders-api \
  --environment ci \
  --allow-ci-context \
  --yes

Noninteractive dependency installation additionally requires:

--allow-install

Read SECURITY.md before enabling verification in automation.

Static agent exports

Static exports are the reliability floor: core capability information remains available even if an agent never invokes MCP.

skillwire export --target claude
skillwire export --target cursor
skillwire export --target agents-md

Install/update a generated export at the consumer's repository-native path:

skillwire export --target claude --write     # CLAUDE.md managed block
skillwire export --target cursor --write     # .cursor/rules/skillwire.mdc
skillwire export --target agents-md --write  # AGENTS.md managed block

For CLAUDE.md and AGENTS.md, SkillWire updates only a marked managed block and preserves surrounding user content. The generated block is excluded from repository-evidence hashing/parsing so exports cannot create self-referential lock drift; surrounding user guidance remains ordinary evidence. Large monorepos receive a bounded static summary plus exact skillwire resolve/skillwire explain fallback instructions instead of an unbounded instruction file. skillwire check verifies that tracked generated content still matches the committed capability lock.

Agent Skills integration

v0.1 ships SkillWire-owned integration profiles for exactly three workflows from addyosmani/agent-skills:

test-driven-development
debugging-and-error-recovery
ci-cd-and-automation

Enable them against already installed skills:

skillwire profile enable addyosmani/agent-skills
skillwire profile validate
skillwire profile list

Or point at an explicit installed directory:

skillwire profile enable addyosmani/agent-skills \
  --skill-dir /path/to/installed/skills

SkillWire does not install, update, publish, or version Agent Skills. GitHub CLI's gh skill already operates in that adjacent package-management lane. Because gh skill is documented as public preview, SkillWire treats its JSON output defensively: it consumes only fields it needs, ignores unknown fields, and falls back to known skill directories when the preview shape is unsupported.

The local companion skill is in profiles/using-skillwire/SKILL.md. Baseline correctness does not depend on that skill activating.

Official GitHub CLI references:

• gh skill manual
• gh skill list manual

Read-only MCP server

skillwire serve --mcp

MVP tools:

list_components
list_capabilities
resolve_capability
explain_capability
get_capability_status

There is deliberately no arbitrary command-execution MCP tool.

The MCP transport is a thin adapter over the same capability engine used by the CLI and static exports. The server implements newline-delimited stdio JSON-RPC, implements the required server/discover probe for the 2026-07-28 protocol, returns current cacheable result metadata from tools/list, and retains a compatibility initialize response for older clients.

Official protocol reference: Model Context Protocol.

Drift checking and CI

Normal CI should use:

skillwire check

Default check:

• recomputes repository evidence fingerprints;
• re-runs deterministic analysis;
• compares current and committed resolutions;
• validates profile fingerprints;
• checks tracked generated exports;
• reports stale capability tuples;
• executes zero repository commands.

Explicit reverification is separate:

skillwire check --verify

Opting into dependency installation or CI-scoped commands requires the same explicit gates:

skillwire check --verify --allow-install --allow-ci-context --yes

If static drift is present, verification does not run until the drift is reviewed and refreshed.

Benchmark and release evidence

The public benchmark is intentionally split into two tiers. The canonical Tier 1 manifest contains 20 public repositories pinned to exact commit SHAs with reviewed expectations. --prepare creates clean exact-SHA checkouts and refuses existing targets.

Tier 1 — resolution

Tier 1 executes no repository commands and reports independent headline metrics for:

• resolution accuracy;
• reviewed ambiguity rate;
• override requirement rate;
• time to first useful capability (mean/p50/p95).

It also records a raw capability ambiguity diagnostic and per-repository errors/classifications.

skillwire benchmark \
  --manifest benchmark/public-repositories.json \
  --repos-dir /tmp/skillwire-public-20 \
  --prepare \
  --output benchmark/results/public-20-resolution.json

Tier 2 — execution

A smaller eligible subset uses the explicit non-isolated verification path and classifies results as:

verified_success
resolution_wrong
environment_missing
baseline_project_failure
dependency_installation_required
ambiguous
unsupported
execution_prohibited
input_required

skillwire benchmark \
  --manifest benchmark/public-execution-subset.json \
  --repos-dir /tmp/skillwire-public-execution \
  --prepare --execute --yes --allow-install \
  --output benchmark/results/public-execution-subset.json

.github/workflows/benchmark.yml is the canonical reproducible public run and uploads the raw JSON, summaries, environment metadata, manifests, and review record as workflow artifacts. Public benchmark claims must come from those unedited run artifacts, never fixture-derived or hand-authored result files.

CLI surface

skillwire init
skillwire inspect
skillwire refresh
skillwire components
skillwire resolve <capability>
skillwire explain <capability>

skillwire override set
skillwire override list
skillwire override show
skillwire override remove
skillwire override verify

skillwire verify <capability>

skillwire profile enable
skillwire profile validate
skillwire profile list
skillwire profile show
skillwire profile disable

skillwire export --target <claude|cursor|agents-md>
skillwire serve --mcp
skillwire check
skillwire check --verify
skillwire benchmark

skillwire version
skillwire schema list
skillwire schema show <name>
skillwire validate capability <file>
skillwire validate lock <file>

Architecture

Repository evidence
        ↓
Deterministic analyzers
        ↓
Repository model
        ↓
Capability candidates
        ↓
Resolver
  ├── component scope
  ├── environment scope
  ├── authority precedence
  └── project overrides
        ↓
RepositoryCapability contracts
  ├── provenance
  ├── effects
  ├── verification
  └── evidence fingerprints
        ↓
  ┌───────────┬──────────────┬───────────────┐
  │ CLI       │ static export│ read-only MCP │
  └───────────┴──────────────┴───────────────┘
        ↓
non-executing CI drift check

The execution subsystem is deliberately separate from resolution. LocalBackend is the only MVP backend and makes no isolation claim.

Engineering constraints

• pure Go core;
• CGO_ENABLED=0 supported;
• no native Go plugins;
• no required Python or Node helper process;
• no third-party Go module dependency in v0.1;
• structured direct process execution instead of a shell;
• repository-relative portable path validation;
• deterministic committed artifacts;
• typed uncertainty;
• fixture-driven and adversarial tests;
• MCP as a transport, not the domain engine.

MVP non-goals

v0.1 deliberately excludes:

• skill installation or publishing;
• multi-agent orchestration;
• Git worktree management;
• a web dashboard or cloud service;
• production deployments;
• database migrations;
• Kubernetes or Terraform execution;
• telemetry querying;
• browser automation;
• arbitrary MCP execution;
• strong sandbox/isolation claims;
• native Go plugins or cgo;
• required external language analyzers;
• LLM-based repository interpretation.

Development

Building from source requires Go 1.23+:

make build
make check
make test-race
make cross-build

Run the fixture-backed lifecycle manually:

make build
./bin/skillwire inspect --root testdata/repositories/node-pnpm-workspace

See:

• docs/architecture.md
• docs/on-disk-layout.md
• docs/testing.md
• docs/release.md
• benchmark/README.md

License

MIT License. See LICENSE.