Skill Assembly

Skill Assembly is an Agent Skill Manager that organises existing Skills, assembles the right capabilities for each task, and saves useful routes as reusable Skills.

Install it once, continue using your Agent normally, and choose “Save this for next time?” only when a successful route is worth keeping. Sources, Capabilities, Routes, compiler state, and Host projections stay behind that normal Task → Result experience.

Supported Host

V1 supports Codex when its current plugin and trusted synchronous SessionStart hook surfaces are available. Skill Assembly installs one owned Codex plugin containing:

• one tiny bootstrap hook for startup, resume, clear, and compact;
• one progressively disclosed $skill-assembly gateway Skill.

It does not edit AGENTS.md, existing hooks, or existing Skills. Codex requires one explicit hook review/trust confirmation before Skill Assembly reports the Host integration as active.

Install

From a cloned release, the shortest source install is:

python3 scripts/install.py

The installer uses pipx when available, otherwise uv tool, then creates the per-user Instance, detects Codex, registers the owned plugin, and verifies its physical and loaded state. Review and trust the single Skill Assembly hook in Codex /hooks, then finish verification:

skill-assembly verify

For a published Python package, the fully standard lifecycle is deliberately explicit because Python wheels do not have safe post-install mutation hooks:

pipx install skill-assembly
skill-assembly install

Availability, activation, trust, and execution evidence are reported separately. An untrusted hook leaves the Instance in pending-host-trust; it is not described as installed successfully.

Normal use

Ask Codex for work as usual. The tiny bootstrap applies this gate:

Matching saved Route?                  → use it
Explicit native capability completes? → use it
Neither?                               → plan first, resolve Capabilities, close the Route

When a new Route succeeds and has reuse value, Codex offers:

Save this for next time?

Choosing yes saves the Route map in your Skill Assembly data. Raw Skills remain read-only, and the Codex gateway loads full managed state only when needed.

Useful diagnostics:

skill-assembly status --live
skill-assembly paths
skill-assembly index
skill-assembly route list

Update and uninstall

pipx upgrade skill-assembly
skill-assembly install       # migrate/repair and re-verify the Host projection

skill-assembly uninstall     # remove only owned Codex integration; preserve local data
pipx uninstall skill-assembly

Permanent local data removal is intentionally separate and irreversible:

skill-assembly data remove --yes

Data locations

Skill Assembly uses the operating system's familiar per-user application directories through platformdirs:

Platform	Durable User Data	Rebuildable Cache
macOS	~/Library/Application Support/Skill Assembly	~/Library/Caches/Skill Assembly
Linux	~/.local/share/Skill Assembly	~/.cache/Skill Assembly
Windows	%LOCALAPPDATA%\Skill Assembly	%LOCALAPPDATA%\Skill Assembly\Cache

The fixed Constitution, managed Sources, Capabilities, Routes, and saved Skills are User Data. Indexes and temporary builds are Cache. Existing Host Skills are never moved or edited.

Architecture and evidence

• Architecture
• Product authority and boundaries
• Initialisation and data isolation
• Codex Host Adapter
• Method Resolution Records
• Original state and migration note
• Contributing

Run the focused test suite:

uv sync --extra dev
uv run pytest -m "not corpus"

Run the complete local release gate, including the exact pinned public corpus:

uv run python scripts/release_gate.py --full-corpus

No upstream corpus code is executed. The corpus is disposable read-only Source input and is never included in the repository or release artifacts.