instill #

Install agent skills into any AI coding tool, from a folder, a git repository, or a signed HTTP index.

About #

AI coding tools read skills from their own folders, so keeping the same skills in several tools means copying them by hand and hoping every copy stays the same. instill installs the same skills into every destination in one run, checks the bytes it installs, and writes a record so you can tell later whether a copy on disk still matches what was published.

It reads skills from a local folder, a git repository, or an HTTP source that carries a discovery index. When a source carries an index, the index is the authority: every payload is digest-checked against it, and a signed index must verify against the signers file you pin.

Features #

• One install into many destinations, including the shared .agents/skills folder that a number of tools read.
• Sources: local folders, git repositories with an optional ref and subdirectory, and HTTP sources with a discovery index.
• Trust: SSHSIG signature checks on the index, sha256 digests on every payload, and install records that verify checks the disk against.
• Browse before you install: instill list and instill find read a source's catalog without downloading the payloads.
• Keep installs current with instill update, and take them out with instill remove.
• A Go library with no third-party dependencies, so your own tool can embed the same engine.

Installation #

go install tangled.org/mads.havmand.eu/instill/cmd/instill@latest

That binary reports the version it was installed from, so instill version prints the tag, for example v0.1.1.

Or with Homebrew:

brew tap mads.havmand.eu/instill https://tangled.org/mads.havmand.eu/instill.git
brew install mads.havmand.eu/instill/instill

Requirements:

• Go 1.27 to build from source.
• git for git sources.
• ssh-keygen for signed indexes. It ships with OpenSSH.

To build from a checkout:

mise exec -- go build ./cmd/instill

Release tags carry prebuilt binaries for Linux (amd64 and arm64) and macOS (arm64). They are attached to the tag and can be downloaded from the tag page.

Usage #

A skill is a directory with a SKILL.md file in it. Everything else in the directory, such as scripts or assets, installs with it.

skills/
  deploy/
    SKILL.md
    scripts/run.sh

Install those skills into a tool:

instill --harness claude

That reads ./skills, writes .claude/skills, and records what it installed. Installing is the default command, so instill install says the same thing.

Commands #

Command	What it does
instill [skill...] [source]	Install skills into a harness skill folder. This is the default.
instill find <query> [source]	List the skills whose name or description match the query
instill list [source]	List every skill a source offers
instill install [source]	The same install, spelled out
instill remove <skill>...	Delete skills and their install records
instill update	Fetch each recorded source again and reinstall the recorded skills
instill status	Show the skills installed in each destination
instill validate [source]	Lint skills without installing them
instill verify	Compare installed skills with their records
instill index verify <source>	Check a source's index and its payload digests
instill version	Print the version

Flags #

Flag	Meaning
--scope project|global	Work in the project directory (default) or in the home directory. --user is the older name for --scope global and still works.
--skills <list>	Comma-separated names of the skills to install.
--harness <list>	Comma-separated destinations.
--source <source>	The source to search or to list.
--frozen-lockfile	Install exactly what the lock records, and fail when the source has moved on.
--signers <file>	An ssh-keygen allowed_signers file naming the keys trusted to sign discovery indexes.
--allow-unsigned	Accept an unsigned index. A signature that is present still has to verify.

Examples #

# Browse a source before installing from it
instill list https://example.com/skills
instill find audit

# Install one skill into one tool, at the home level
instill --scope global --skills github-repo-config-audit --harness claude

# The same thing, with the skill name as an argument
instill --scope global github-repo-config-audit --harness claude

# Install from a git repository, pinned to a ref, reading one subdirectory
instill git@host:me/skills.git#v1.2
instill git@host:me/monorepo.git#:skills
instill --scope global crafting-effective-readmes --harness claude,agents \
  "https://github.com/softaworks/agent-toolkit.git#:skills"

# Name a source and a skill in one argument
instill "https://github.com/softaworks/agent-toolkit.git#:skills::crafting-effective-readmes"

# Install into two tools at once
instill --harness claude,agents

# Refresh what the records name, and take skills out again
instill update --scope global
instill remove --scope global github-repo-config-audit

The source is a URL or a path, such as ./skills or a git URL. A bare name is a skill to install, so a folder source needs the path in front of it. A source and a skill may also be written as one target, as in source::skill. Flags may come before or after the arguments.

Declaring what a project installs #

A manifest says which skills a project wants and where each one comes from. The lock beside it pins the bytes those declarations resolved to. Both files are meant to be checked in, so a teammate gets the same skills:

# Declare what the project wants
instill manifest add ./skills deploy
instill manifest add "https://github.com/softaworks/agent-toolkit.git#:skills" crafting-effective-readmes

# Install it and write the lock
instill

# Check that the lock still matches the sources
instill lock --check

# Install exactly what the lock records, and fail when a source moved
instill --frozen-lockfile

The manifest is skills.json at the project root, and the lock is skills.lock.json beside it. The user-level pair lives in ~/.config/instill. The formats and their JSON schemas are in docs/reference/manifest-and-lock.md.

Destinations #

instill knows the skill folder of every tool it supports. The full list, with the project and home folder for each one, is the harness table in docs/systems/install-and-harnesses.md. Name a destination with --harness, for example --harness claude or --harness claude,agents. Tools that read the shared folder, such as Droid, are served by a copy in agents alone, so naming both in one list skips the redundant install and prints a note.

The agents destination is the shared folder of the Agent Skills standard. One install there serves every tool that reads the shared folder, so you keep one copy instead of one per tool. Tools that read only their own folder, or releases that predate the shared folder, need their own install.

Documentation #

The full documentation lives in docs/:

• Architecture: the layers, the install flow, the catalog flow, the update flow.
• Sources: how each source kind is fetched and checked, and the index format.
• Records and verification: the install record and the verify states.
• Manifest and lock: the two files that declare and pin what a project installs.
• Security and trust: the signature and digest model, and its limits.
• Glossary: the terms this project uses.

Library #

The root package instill is the reusable library. One import gives you skill discovery, harness definitions, the catalog, and the install engine:

import "tangled.org/mads.havmand.eu/instill"

skills, err := instill.Discover("skills")          // find skill folders
h, err := instill.Get("droid")                     // pick a target tool
res, err := instill.Install(instill.Options{       // copy and record
    Skills:  skills,
    Harness: h,
    Level:   instill.LevelProject,
    Root:    ".",
})

Contributing #

Contributions are welcome. Start with docs/how-to-contribute, which covers the branch and review cycle, the test conventions, and how to add a harness.

Development setup:

mise exec -- go test ./...
mise exec -- go vet ./...

Tests are written first and kept small. The project has no third-party dependencies.

License #

instill is licensed under the MIT license. See the LICENSE file.