farrier
farrier renders an agent-neutral prompt library into a repository — generating
the skill, prompt and instruction adapters expected by Codex, Claude, and GitHub
Copilot, plus the launcher scaffolding (.agents/agents.mk and friends) that keeps
those adapters current.
A farrier is the craftsman who fits the right gear onto each horse. This tool fits the shared prompt library onto each repository — and refits it as the library moves, so an architecture, testing or review standard changes in one place and every repository's installed copy follows, instead of each one drifting on a private copy.
Install
pipx install farrier # or: uv tool install farrier
The farrier package ships no library content of its own. Content resolves across two layers: the base library — plain data, the toolchain skills and the packs that select them, with nothing to install or import — and an optional private overlay that shadows it name-for-name. Point farrier at an overlay once:
farrier config set-library /path/to/the/overlay
farrier config show
config writes one shared TOML file, ~/.config/stablemate/config.toml
(~/Library/Application Support/stablemate/ on macOS, %APPDATA%\stablemate\ on
Windows; $STABLEMATE_CONFIG overrides it). Every stablemate tool reads and writes that
same file, so library_dir and base_dir mean one thing across all of them — a
pre-existing ~/.config/farrier/config.toml is still read, and folded in on the first
write.
Finding the base library. farrier discovers the base via, in order,
$STABLEMATE_BASE_DIR → the base_dir config key (farrier config set-base <path>) →
a configured stablemate_dir checkout (<checkout>/base-library) → the shared cache at
~/.cache/stablemate. The cache is deliberately last, so a fetched copy can never shadow
a checkout you are editing.
farrier install fetches the base, and updates it. It is the only command that
touches the cache, so under pipx — where each tool is its own venv and the base is data
with no package to import — you get a working base library without configuring anything.
The base library comes from this farrier's release tag (farrier-v<version>), so the
library always matches the farrier that renders it. A farrier installed from a checkout or a
git URL tracks main instead. The fetch needs git and network
access. An update asks the remote which commit that ref names first, so an already-current
cache costs one round-trip rather than a re-clone. Three qualifications:
- A base you named is never fetched over. If
$STABLEMATE_BASE_DIR,set-baseor astablemate_dircheckout answers, install returns it without even probing the remote. --checkfetches but never updates. It writes nothing and runs in CI, where a library moving underneath the comparison would make the result depend on the hour.- Failure keeps what works. Offline,
STABLEMATE_FETCH_BASE=0, or a broken clone all leave the existing cache in place rather than leaving you with none.
STABLEMATE_FETCH_BASE=0 forbids the network entirely; STABLEMATE_CACHE_DIR relocates
the cache. See the monorepo's
install guide
for the full resolution order and why everything other than install reads the cache frozen.
Use
In a repository that has no agents.yml yet:
farrier init # write a starter agents.yml (--force to replace one)
init reads nothing — no library, no config — so it works on a fresh machine before
farrier config set-library. It refuses to overwrite an existing agents.yml.
Then, from a repository that has one:
farrier --repo . # render/install the selected packs
farrier --repo . --check # verify generated files are up to date (no writes)
Rendering is the default action; farrier install --repo . is an accepted alias
of farrier --repo .. A bare farrier with no arguments prints the verb listing.
Install has two scopes, and each one writes only where it is pointed. --repo PATH
renders the repo's agents.yml selection under PATH and nothing else. --user renders
the [user_library.<harness>] tables of the shared config into the harness homes
(~/.claude, and ~/.agents for Codex and Copilot), reads no repo and writes to none.
Pass both, farrier install --repo . --user, to refresh the home right after the repo
from the same library. A repo install never touches the home on its own, so a worktree
on an older branch cannot overwrite the skills your main checkout installed there.
The rest of the verbs:
farrier config show # every config key as key=value
farrier config show --profile cheap # one [profiles.<name>] table, flattened
farrier config --config ./c.toml show # …read from that file rather than the home one
farrier source .claude/skills/x/SKILL.md # the library file that generated an adapter
farrier eject <name> # hand a generated skill or a policy over to the repo
farrier scaffold --list # the scaffolds this repo may apply, and their params
farrier scaffold <id> [--param KEY=VALUE] # seed repo files from one
farrier workflows # the workflows installed on this machine
farrier version
source takes the path of a generated file and prints the library file behind it. It
is the one to reach for before editing anything under .claude/, .codex/ or
.github/: those are outputs, and an edit there is discarded by the next install.
eject <name> stops farrier managing one thing and keeps its content. Given the
installed name of a generated skill folder (myrepo-db), it strips the farrier
provenance from the folder (the generated_by, source, resolve, do_not_edit and
name metadata keys, plus the banner and farrier source line of bundled files),
then edits agents.yml so nothing selects the skill again. A literal skills: entry
loses its line, a glob entry becomes the literal ids it still matches, and a skill
that only a pack selects goes under exclude.skills. Comments and every other byte of
agents.yml stay. It refuses when more than one harness holds a real copy: set
skills_from on the others first. Given a policy listed in localInstructions, it
writes the policy body into each mapping's text: (ahead of any text there) and
removes the name from policy/policies. After either, it reinstalls, so
farrier --repo . --check passes. A skill name wins over a policy of the same name.
A localInstructions skill: name that no selected library skill carries resolves
to the hand-written skill folder of that name, which is how an ejected skill stays
embedded in AGENTS.md.
config show --profile <name> prints one [profiles.<name>] table — the named model
set a run selects with workhorse-<name> run --profile <name> — flattened to one dotted
line per leaf (power.high.claude.model=haiku). A profile replaces the top-level
tables rather than layering over them, so what it prints is the whole config that run
resolves from, and two profiles diff against each other line by line. --config PATH
goes before the action and names the file every config verb reads and writes, so the
question can be asked of a config that is not this machine's home one. There is no
setter: a profile is a nested table, and set-library-style flat assignment cannot
express one — edit the file.
Configuring agents.yml
agents.yml (at your repo root) selects what farrier renders. farrier init writes a
starter one with the common keys as commented examples. Every option —
repo, agents, packs, skills/prompts/roots, scaffolds, exclude,
localInstructions, template/vars, and workflow — is documented with
inline comments in agents.example.yml. Copy it to
your repo as agents.yml and prune to taste.
Each agents.<harness> is true, false or {skills_from: <other harness>}. The
mapping enables the harness and renders no skill folders for it. Instead farrier
writes a relative symlink <its skills dir>/<name> to ../../<source skills dir>/<name> for every skill folder of the source harness, hand-written ones
included, so one set of skills serves several harnesses:
agents:
claude: true
codex:
skills_from: claude
The source must be an enabled harness that does not itself link. Prompts, commands,
root instructions and hooks still render per harness. A cross-skill link inside a
shared copy points at the source harness's home skills dir. A symlink in a linked
dir that targets the source dir is farrier-owned: install rewrites a wrong one and
sweeps a stale one, and --check reports a missing, extra or wrong one as drift. A
real folder or a foreign symlink there is not owned and follows the usual conflict
rules.
Library layout
The other side of the contract is the agent library farrier renders from — what
goes in library/skills/, library/prompts/, packs/ and scaffolds/, the file
formats expected, and how source names map to generated adapters. That is documented in
docs/LAYOUT.md.
A skill or prompt is markdown with YAML frontmatter, and farrier.frontmatter reads it
with a markdown parser and yaml.safe_load — never a fence regex. (It is farrier's own
module rather than ostler.markdown because farrier needs frontmatter only and does not
depend on ostler; both follow the same rule, which make check-parsers enforces.) A CRLF file, a closing --- with a trailing space and a file with
no newline after it are all ordinary documents, and the regexes that preceded this read
every one of them as having no frontmatter at all.
Farrier does not install workflows. A library ships none, agents.yml has no
workflows: key, and nothing is written to .agents/workflows/. A workflow is a Python
distribution that brings its own command: install it with pip/uv and run it directly.
uv tool install workhorse-workflows
workhorse-research run --dry-run # static preflight, drives nothing
workhorse-coder run
Locating the library
--library DIR, $FARRIER_LIBRARY_DIR and library_dir in the home config
(farrier config set-library) select the overlay, in that precedence. The base
library is found separately, by the order under Install above, and the two
stack: the overlay first, then the base.
A directory counts as a library if it holds library/ — that is the whole contract.
Point farrier at one that does not and it exits with a setup hint; configure no overlay
at all and it runs base-only, which is a supported setup rather than an error. Only with
neither an overlay nor a base does it refuse to start.
Related
workhorse-agent— the fail-soft runner that executes the workflows, against the adapters farrier renders.ostler— the documentation-graph toolkit workflows call through its in-process Python API.
All three live in the stablemate workspace.
Metadata
Release files for farrier 5.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| farrier-5.0.0.tar.gz | 96.1 kB | With provenance | Details for farrier-5.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| farrier-5.0.0-py3-none-any.whl | Python 3 | none | any | Details for farrier-5.0.0-py3-none-any.whl |
Total release size: 199.8 kB
Release files / farrier-5.0.0.tar.gz
| Download URL | farrier-5.0.0.tar.gz |
|---|---|
| Size | 96.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8deaa83c0b1a5de12b6c8b786cd4216692cffa96fd71ce35af804b9a04909517
|
|
BLAKE2b-256 checksum How to use checksums |
9e96a49cdd1f9d070d3eeb8dc9b408f21d89a352309d4c76c5a84a18920ff305
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logRelease files / farrier-5.0.0-py3-none-any.whl
| Download URL | farrier-5.0.0-py3-none-any.whl |
|---|---|
| Size | 103.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d9eb17a35e54241768d94546cd3d5de863c02b75527cb222637ae2699c29652
|
|
BLAKE2b-256 checksum How to use checksums |
f4b9d087018966d6bec896ec59aee941cfdbfe46d9ce515600b41efcba809be2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logSecurity for farrier 5.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for farrier-5.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.