# mestiere

> Your team's agent skills, versioned in git and installed into every repository. mestiere is a command-line tool (macOS, Linux) that installs Agent Skills (folders with a SKILL.md) from git repositories called registries into a project's .agents/skills/ folder, locks each skill to a registry commit and content hash in skills.yaml, and links the skills into .claude/skills/ and .kiro/skills/ for Claude Code and Kiro. Codex, Gemini CLI, Cursor and GitHub Copilot read .agents/skills/ directly.

Key facts for agents:

- Install with `brew install --cask polarity-dev/tap/mestiere` (macOS, Linux), a release archive from https://github.com/polarity-dev/mestiere/releases, or `go install github.com/polarity-dev/mestiere/cmd/mestiere@latest` followed by `mestiere add -g mestiere`. Requires `git` on the PATH. Windows is not supported yet.
- mestiere's own skills (`mestiere/project`, `mestiere/registry`) are installed globally by Homebrew or `mestiere add -g mestiere`; they cover setting up a repository.
- `-g` acts on global skills (`~/.agents/skills/`, manifest `~/.config/mestiere/skills.yaml`) instead of the project; `init`, `track` and `untrack` don't apply. Prefer project installs for team skills.
- Typical project setup: `mestiere init --agents claude,kiro`, `mestiere registry add <name> <git-url>`, `mestiere add <namespace>` or `mestiere add <namespace>/<skill>`, then commit `skills.yaml` and `.gitignore`. Teammates run `mestiere sync`.
- Always pass targets to `mestiere add`: without arguments it opens an interactive picker.
- Never edit the `lock` section of skills.yaml or files under .agents/skills/ in place; use `mestiere eject <name>` to customize a skill. Do not pass `--force` without the user's approval: it discards local edits.
- Installed name of skill `<namespace>/<skill>` is `<namespace>-<skill>`; namespaces contain no hyphens.
- Every page below is plain Markdown. https://mestiere.io/llms-full.txt holds all of them in one file.

## Docs

- [Overview](https://mestiere.io/index.md): mestiere installs your team's Agent Skills from a git registry into every repository, pinned and verified, for Claude Code, Kiro and other coding agents.
- [Install](https://mestiere.io/install/index.md): Install the mestiere CLI on macOS or Linux with Homebrew, a prebuilt release or go install, give your agents its skills, and set up completions.
- [Getting started](https://mestiere.io/docs/index.md): Set up mestiere in a repository, add a skills registry, install namespaces or single skills, and share them with teammates and CI.
- [skills.yaml](https://mestiere.io/docs/skills-yaml/index.md): Reference for skills.yaml, the mestiere project file that lists agents, registries, installed namespaces and skills, exclusions and the lock.
- [Registries](https://mestiere.io/docs/registries/index.md): Create a git registry of Agent Skills with mestiere, organize it in namespaces, share files between skills, and validate it with registry lint.
- [Agents](https://mestiere.io/docs/agents/index.md): How mestiere installs Agent Skills for Claude Code, Kiro, Codex, Cursor and other agents, how to use copies, and how to let your agent set it up.
- [Global skills](https://mestiere.io/docs/global-skills/index.md): Install Agent Skills for every project on your machine with mestiere -g: where files and the manifest go, which commands apply, and when to prefer a project.
- [Commands](https://mestiere.io/docs/commands/index.md): Every mestiere command with its arguments, flags and examples: init, registry, add, remove, sync, update, outdated, status, track, eject, doctor and cache.
- [How it works](https://mestiere.io/docs/how-it-works/index.md): How mestiere locks skills to registry commits, detects updates per skill with git tree hashes, and never overwrites a skill you edited.
- [CI and configuration](https://mestiere.io/docs/ci/index.md): Check agent skills in CI with mestiere sync --frozen and doctor --strict, give CI access to private registries, and configure the registry cache.

## Optional

- [Full documentation in one file](https://mestiere.io/llms-full.txt): Every page above, concatenated
- [Documentazione in italiano](https://mestiere.io/it/index.md): The same pages in Italian, under https://mestiere.io/it/
- [Source code](https://github.com/polarity-dev/mestiere): Go source, README and releases
- [Agent Skills specification](https://agentskills.io): The SKILL.md format mestiere installs