Skillweft

The right capabilities, woven into each project.

Skillweft is the successor to easyskillz, from the same author. easyskillz fully materialized every skill into each host's native directory; that worked, but a large library meant advertising far more to the model than any one task needed. Skillweft takes the opposite approach: skills stay hidden in a library until a router searches and opens exactly the one snapshot a task needs.

Skillweft keeps large Agent Skills libraries outside native agent discovery and advertises only the small working set a project needs. One compact router lets an agent search metadata and open one trusted, immutable skill snapshot for the current task.

It is not another skill installer. It does not fetch remote code, silently enable MCP servers, or pretend every agent can hot-reload capabilities.

Why

Agent hosts usually expose every enabled skill's name and description to the model. A library of hundreds of skills can consume material context before any skill body is used. Skillweft separates six states:

• Library: indexed locally, outside host discovery.
• Pinned: selected for automatic advertisement by a global default, profile, or project.
• Searchable: hidden from native discovery but discoverable through the router.
• Blocked: unavailable to search, open, and project discovery.
• Advertised: physically verified in the project's native discovery surface.
• Loaded: already present in a conversation; Skillweft reports this as unknown because files cannot remove model context retroactively.

MCP definitions remain a fourth, higher-risk state. Version 0.1 inventories and proposes them but never changes host configuration or starts a server.

Status

Skillweft 0.1 is an early public release. Its storage and materialization boundaries are extensively tested, but host behavior can change independently. Treat reload estimates as conservative guidance, not a promise that an existing conversation changed.

Quick start

Requires Node.js 22 or newer.

npm install --global skillweft

# Or run without a global install:
npx skillweft --help

Configure an explicit local skill library:

skillweft source add personal /path/to/my-skills --yes
skillweft index --yes
skillweft trust personal/pdf-tools --yes

skillweft search "extract tables from a PDF" --json
skillweft open personal/pdf-tools --json

open returns a content-addressed SKILL.md snapshot. It does not add the skill to .agents/skills or .claude/skills.

For repeated project use:

skillweft router install --host codex --yes
skillweft profile create work --yes
skillweft profile add work personal/pdf-tools --yes
skillweft profile use work --yes

skillweft apply --host codex          # preview only
skillweft apply --host codex --yes    # apply owned copies
skillweft status --host codex --json

For a small automatic baseline across projects:

# User-local default inherited by projects; this does not write a host-global skill.
skillweft policy pin personal/security-review --scope global --yes

# Add or suppress capabilities for this project.
skillweft policy pin personal/accessibility --yes
skillweft policy block personal/wordpress --yes

# Reconcile the effective policy into this project's native host surface.
skillweft apply --host codex --yes
skillweft policy show --json
skillweft context --host codex --json

Global defaults deliberately require apply in each project. This makes a project block authoritative; ordinary skills are never copied into a host-global discovery directory where the project could not reliably hide them.

Project skill surfaces:

| Host | Surface | Conservative result | |---|---|---| | Codex, Copilot, Cursor | .agents/skills | restart required | | Gemini CLI | .agents/skills | interactive reload action required | | Antigravity | .agents/skills | restart required | | Devin | .agents/skills | reload required | | Claude Code | .claude/skills | reload required |

The result describes catalog discovery, not content already loaded into a conversation.

Router workflow

The embedded skillweft-router tells an agent to:

1. Use an already pinned capability when it fits.
2. Search hidden metadata when the required capability is not advertised.
3. Select one qualified ID and open one trusted immutable snapshot.
4. Read that file directly for the current task.
5. Propose a project or global pin only when repeated visibility is worth the context cost; never persist it silently.

Project installation is shown above. Global router installation is also available where the host documents a user-level root:

skillweft router install --host claude --scope global --yes
skillweft router install --host codex --scope global --yes

Devin global skills are intentionally unsupported because its official product documentation does not define a global discovery contract.

Visibility precedence

skillweft profile pin work personal/api-design --yes
skillweft profile unpin work personal/api-design --yes
skillweft activate personal/debugging --host codex --yes
skillweft deactivate personal/pdf-tools --host codex --yes

Effective precedence is global defaults, then profile pins, then project pins, then project blocks. The last matching layer wins. profile add/remove remain compatible aliases for skill pins, while activate/deactivate remain convenience commands that update project policy and apply it to a host.

Pinning does not grant trust. Skillweft still refuses untrusted skills, ambiguous names, unowned collisions, and drifted outputs. There is no --force escape hatch.

MCP inventory is read-only

skillweft mcp inventory --file ./mcp-definitions.json --json
skillweft profile add work github --kind mcp --yes
skillweft mcp propose work --file ./mcp-definitions.json --json

Output retains safe command or sanitized URL shape, scopes, environment-variable names, header names, and argument counts. Literal arguments, secret values, URL credentials, query strings, and fragments are discarded. Skillweft 0.1 exposes no MCP apply or launch command.

Mutation rules

• Without --yes, non-interactive mutations are previews and perform zero writes.
• Interactive mutations show one plan and ask once.
• Owned active sets are copy-only and journaled.
• State commits last; normal failures roll back, and a later run recovers a crash journal.
• User-owned and drifted files are preserved.

All commands support --json. JSON mode writes exactly one envelope to stdout and nothing to stderr, including on errors. Human-readable errors are written to stderr. Exit codes are 0 for success, 1 for operational errors, and 2 for usage or argument errors.

Success envelopes have { "schema": 1, "ok": true, "command", "result" }. Error envelopes have { "schema": 1, "ok": false, "command", "error": { "code", "message", "details"? } }.

Development

npm ci
npm test
npm run test:coverage
npm audit --audit-level=high
npm run test:package
npm run ci

The package gate installs the packed artifact in a clean fixture and uses its installed wrapper for inherited pin → project block → unblock/project pin transitions, exact native discovery contents, hidden → active → hidden compatibility, crash-journal recovery, MCP proposal redaction, host-config immutability, and stdout/stderr/exit behavior.

Security boundary

Skills are executable instructions, not harmless Markdown. Skillweft indexes only explicit local roots, rejects filesystem indirection and broad/overlapping roots, bounds metadata and tree size, snapshots content by hash, requires local trust before opening, and never interpolates metadata into a shell command.

See AGENTS.md for the invariants contributors must preserve.

Security reports belong in a private GitHub security advisory, not a public issue. See SECURITY.md. Contributions are welcome under CONTRIBUTING.md and the Code of Conduct.

License

MIT