# Cookbook

Copy-paste Kasetto setups for teams, monorepos, multiple agents, and pinned rollouts.

**When you need this:** You want copy-paste setups for common real workflows (teams, monorepos, multiple agents, pinned rollouts).

**What you'll learn:**

- Patterns that work well in practice
- How to pin and roll out changes safely

## Reproducible Team Setup (Commit the Lock)

Treat `kasetto.lock` like `Cargo.lock` or `package-lock.json`: commit it next to `kasetto.yaml` so every teammate gets identical skill versions.

```bash
# Maintainer: set up the config, sync, then commit both files.
kst sync --project
git add kasetto.yaml kasetto.lock
git commit -m "chore: pin agent skills"
```

```bash
# Teammates: clone, then sync. The lock is honored exactly:
# no surprise upgrades, and no network fetch when nothing changed.
kst sync
```

```bash
# Maintainer rolls versions forward, then commits the updated lock.
kst sync --update          # re-resolve branches/HEAD, rewrite pins
# or update one entry: kst sync --update code-reviewer
git add kasetto.lock
git commit -m "chore: bump agent skills"
```

```bash
# CI verifies the checked-in lock without ever fetching new versions.
kst sync --locked --project
```

`--locked` (alias `--frozen`) errors if the config needs something the lock can't satisfy, so a stale lock fails the build instead of silently drifting. See [CI & automation](/docs/ci) and [How Sync Works → The Lockfile Contract](/docs/how-sync-works#the-lockfile-contract).

## Edit Your Config Without Leaving the Shell

`kst add` / `kst remove` rewrite `kasetto.yaml` (comments preserved), then sync (the cargo/uv way). Paste a tag-pinned URL with the `@<ref>` shorthand and you're done:

```bash
# Pin a pack to a specific tag. The `@<ref>` shorthand equals `--ref <ref>`.
kst add https://github.com/anthropics/skills@v1.2.0

# Add named skills from a multi-pack repo (kind-tagged, repeatable).
kst add https://github.com/example/repo --skill code-reviewer --skill find-skills

# Touch several sections in one edit: skills + MCPs + commands + instructions together.
kst add https://github.com/example/repo --skill find --mcp github --command review --instruction conventions

# Preview the edit without writing kasetto.yaml or running sync.
kst add https://github.com/example/repo --dry-run

# Edit the config but skip the install (sync later or in CI).
kst add https://github.com/example/repo --no-sync
```

`kst remove` is the symmetric reverse: same kind-tagged flags, with `*` to drop a whole entry:

```bash
# Drop the source from every list it appears in, prune installed assets.
kst remove https://github.com/example/repo

# Subtract just one skill; if it was the last name, the whole entry is dropped.
kst remove https://github.com/example/repo --skill code-reviewer

# Drop the whole MCP entry (the lone `*` means "this kind's entry").
kst remove https://github.com/example/repo --mcp "*"

# Same `@<ref>` shorthand for disambiguating when one URL appears twice.
kst remove https://github.com/example/repo@v1.2.0
```

Both honor `--locked`/`--frozen` (the follow-up sync refuses to fetch), `--json` (structured output for scripts), and `--no-sync` (edit the YAML only). Deep `blob`/`tree` browse URLs work too. Paste the URL you're already looking at and Kasetto decomposes it into `source` + `ref`/`branch` + `sub-dir`.

## Verify the Lock in CI Without Installing

`kst lock --check` (aliases `--locked`/`--frozen`) re-resolves the config and compares against `kasetto.lock`. It exits non-zero on drift and never writes. Cheaper than a full `sync --locked` when you only need to know "is the committed lock still accurate?":

```bash
kst lock --check
```

When a single dependency needs to roll forward without re-resolving everything, target it with `-P` / `--upgrade-package` (mirrors `sync --update <name>...`):

```bash
kst lock --upgrade-package code-reviewer
```

Other sources keep their existing lock entries; only the source providing `code-reviewer` is re-resolved.

## Team Bootstrap from a URL Config

Host a shared `kasetto.yaml` somewhere reachable over HTTPS (public or private), then have each developer run:

```bash
kst sync --config https://example.com/team/kasetto.yaml
```

For private configs hosted on git providers, set the matching token env var (see [Authentication](/docs/authentication)).

## Inheriting from a Team or Org Base

Use `extends` to compose configs. A common pattern: an org-wide base, a team overlay, and a per-project file that narrows or pins specific entries.

```yaml
# project/kasetto.yaml
extends:
  - https://github.com/acme/skills-base/raw/main/kasetto.yaml
  - https://example.com/team/overlay.yaml

scope: project

skills:
  # Same source as the base → narrows the parent's skills list to one entry.
  - source: https://github.com/anthropics/skills
    skills:
      - skill-creator

  # New source → appended on top of the inherited list.
  - source: https://github.com/acme/internal-pack
    skills: "*"
```

Top-level scalars (`scope`, `agent`, `destination`) replace. `skills` and `mcps` merge by `(source, ref-or-branch, sub-dir)` identity. See [Configuration → Extending Another Config](/docs/configuration#extending-another-config) for the full merge-rules table.

## Monorepo: Project Scope per Workspace

Keep one `kasetto.yaml` per workspace folder and make it project-scoped:

```yaml
scope: project
agent: cursor

skills:
  - source: https://github.com/acme/monorepo-skills
    skills:
      - code-reviewer
      - doc-coauthoring
```

Then run sync from each workspace directory:

```bash
kst sync
```

Each workspace gets its own `./kasetto.lock`.

## Multiple Agents from One Config

Install the same skills (and MCPs) into multiple agents:

```yaml
agent:
  - claude-code
  - cursor
  - codex

skills:
  - source: https://github.com/acme/skills
    skills: "*"

mcps:
  - source: https://github.com/acme/mcp-packs
    mcps: "*"
```

## MCP Packs: Pinning and Rollouts

Pin an MCP pack source to a git tag or commit SHA:

```yaml
agent: claude-code

skills:
  - source: https://github.com/acme/skills
    skills: "*"

mcps:
  - source: https://github.com/acme/mcp-packs
    ref: v2.4.1
    mcps: "*"
```

Roll forward by bumping `ref`, then use `--dry-run` to preview:

```bash
kst sync --dry-run
```

## Explicit MCP Entries (`mcps.mcps`)

If a repository contains multiple MCP files or uses a non-standard layout, list entries explicitly.
Plain strings look up `mcps/<name>.json`; objects let you override the directory:

```yaml
mcps:
  # Names resolved from mcps/ dir (auto .json extension)
  - source: https://github.com/acme/monorepo
    ref: v1.4.0
    mcps:
      - github        # → mcps/github.json
      - linear        # → mcps/linear.json

  # Custom directory via { name, path }
  - source: https://github.com/acme/other
    mcps:
      - name: my-server
        path: tools   # → tools/my-server.json
```