Configuring kasetto.yaml

When --config is omitted, Kasetto looks for config in this order:

1. $KASETTO_CONFIG env var
2. ./kasetto.yaml
3. source: key in $XDG_CONFIG_HOME/kasetto/config.yaml
4. $XDG_CONFIG_HOME/kasetto/kasetto.yaml (or ~/.config/kasetto/kasetto.yaml)

Point it at a specific file or URL with --config, or run kst init for local ./kasetto.yaml (kst init --global writes the global config file). To persist a remote URL as your default, add a source: key to ~/.config/kasetto/config.yaml (see Persisting a Default Remote Config).

Example

# Option A: preset destination by agent (see README for supported agent values)
agent:
  - codex
  - claude-code
 
# Option B: manual destination (takes precedence if both are set)
# destination: ./.agents/skills
 
skills:
  # "*" syncs every skill in the source. Each is a directory with a SKILL.md,
  # discovered in the source root or its skills/ subdirectory
  - source: https://github.com/vercel-labs/next-skills
    # ref: v1.0.0   # pin to a tag or commit; omit to track the default branch
    skills: "*"
 
  # or list skills by name
  - source: https://github.com/anthropics/skills
    skills:
      - doc-coauthoring
      - frontend-design
      - pptx
 
  # sub-dir: resolve the named skills under this path, e.g. skills/productivity/grill-me/
  - source: https://github.com/mattpocock/skills
    sub-dir: skills/productivity
    skills:
      - grill-me
      - caveman
 
  # path: a skill in a non-standard location → <path>/<name>/, here skills/engineering/improve-codebase-architecture/
  - source: https://github.com/mattpocock/skills
    skills:
      - name: improve-codebase-architecture
        path: skills/engineering
 
commands:
  # names resolve to commands/<name>.md in the source (nested dirs namespace, e.g. git:commit)
  - source: https://github.com/gsd-build/get-shit-done
    commands:
      - gsd:explore
      - gsd:fast
 
instructions:
  # instructions wire CLAUDE.md / .cursor/rules / AGENTS.md etc. from instructions/<name>.{md,mdc}
  # "*" syncs every instruction; aggregate files (CLAUDE.md, AGENTS.md) get managed blocks
  - source: https://github.com/pivoshenko/pivoshenko.ai
    instructions:
      - docs-autoupdate
      - multi-agent-dispatch
 
mcps:
  # names resolve to mcps/<name>.json in the source
  - source: https://github.com/pivoshenko/pivoshenko.ai
    branch: main   # track a specific branch (use ref: to pin a tag or commit)
    mcps:
      - github
      - vercel
      - kaggle

Reference

Top-Level Fields

Skill Source Fields

Skill Entry Fields

Each entry in the skills list can be a string (the skill name) or an object:

MCP Source Fields

When mcps: "*", Kasetto auto-discovers MCP config files in this order:

1. .mcp.json at the source root
2. mcp.json at the source root
3. Any .json file inside the mcps/ subdirectory

MCP Entry Fields

Each entry in the mcps list can be a plain string (name) or an object, the same as skill entries:

Paths are resolved relative to the source root; absolute paths are honored as-is. .json is appended automatically when the name has no extension.

MCP config files must contain a mcpServers object with server definitions. Servers are merged into each selected agent's native settings file when that agent supports MCP (e.g., .claude.json for Claude Code, .cursor/mcp.json for Cursor). See how sync works for merge behavior details.

A pack can reference secrets with ${kst_<name>} placeholders (tokens, passwords, API keys) instead of committing them. They're resolved at sync time from the environment or a credentials file. See Secret Injection.

Inline MCP Definitions

For machine-specific servers, omit source and provide name and servers directly. servers has the same shape as a pack file's mcpServers object:

mcps:
  - name: laptop-extras
    servers:
      gitea:
        type: http
        url: https://gitea.internal.example/mcp
        headers:
          Authorization: Bearer ${kst:pass:tokens/gitea-mcp}

Inline and source-based entries can coexist; each entry uses exactly one shape, and a config with duplicate inline names fails to load. With extends, an inline entry replaces a parent entry with the same name. Inline definitions need no fetch, so kst lock pins them fully. Under sync --locked, an inline entry's hash must match the lock (a changed definition is drift), and missing agent settings are restored offline. Removing or renaming an inline entry prunes its servers. Secrets resolve only into agent settings, so use kst sync --update laptop-extras to rotate a secret while the definition is unchanged. Edit inline entries directly in YAML; kst add and kst remove manage source-based entries.

Instruction Source Fields

Instructions wire each agent's instruction file (CLAUDE.md, .cursor/rules/*.mdc, AGENTS.md, .github/copilot-instructions.md, and so on) from a single source. An instruction is Markdown with optional YAML frontmatter, discovered in the source's instructions/ directory.

When instructions: "*", Kasetto walks instructions/**/*.{md,mdc} (nested directories namespace with :, e.g. house:security).

Instruction Entry Fields

Each entry in the instructions list can be a plain string (name) or an object, the same as command entries:

How Instructions Land per Agent

Each instruction is transformed into the target agent's native format. Two destination shapes exist:

• Aggregate file: many instructions merge into one shared file (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, ...). Each instruction is wrapped in a managed <!-- kasetto:instruction:ID ... --> comment block, so your own hand-written content and other instructions in the same file are preserved. remove/clean strip only kasetto's blocks and never delete the file
• Per-instruction directory: one file per instruction. Cursor (.cursor/rules/<name>.mdc) gets reconstructed MDC frontmatter (description, globs, alwaysApply); other directory agents (.windsurf/rules, .clinerules, .continue/rules, ...) get the Markdown body only

globs/alwaysApply are only meaningful for Cursor; they are dropped for agents that don't scope instructions. See supported agents for the per-agent destinations.

Extending Another Config

Use extends to inherit from a parent config. Local relative paths resolve against the extending file's directory; HTTPS URLs are fetched with the same auth env vars as --config.

# child.yaml
extends: ./team-base.yaml
scope: project
skills:
  - source: https://github.com/example/extra-pack
    skills: "*"

extends accepts a single string or a list. With a list, parents merge left-to-right; the child overrides them all.

extends:
  - ./org-base.yaml
  - https://example.com/team-overlay.yaml

Merge Rules

Identity-based merging lets a child narrow a parent's skills: "*" to a specific list, or pin a different ref, while still adding new sources.

Cycles are detected and rejected. Maximum chain depth is 8.

Remote Configs

Kasetto can fetch configs from any HTTPS URL:

kst sync --config https://example.com/team-skills.yaml

Great for sharing a single config across a team without checking it into every repository.

Real-World Example

pivoshenko/pivoshenko.ai is a public config that pulls skills from several community packs for Claude Code and OpenCode:

kst sync --config https://github.com/pivoshenko/pivoshenko.ai/blob/main/kasetto.yaml

Kasetto recognises browser URLs from GitHub, GitLab, and Gitea / Codeberg / Forgejo, and auto-rewrites them to the matching raw-content endpoint. You can paste any of these directly:

• https://github.com/owner/repo/blob/main/kasetto.yaml
• https://gitlab.com/group/repo/-/blob/main/kasetto.yaml
• https://codeberg.org/owner/repo/src/branch/main/kasetto.yaml

Kasetto prints a short note: rewrote browser URL to raw content: ... line so you can see what was fetched. Authentication is resolved against the rewritten host, so the same tokens that work for raw URLs apply here too.

If the URL points to a private repository, Kasetto uses the same token-based authentication as skill sources. See authentication for the full list of supported environment variables.

Persisting a Default Remote Config

To stop passing --config on every run, put the URL in the source: key of ~/.config/kasetto/config.yaml:

# ~/.config/kasetto/config.yaml
source: https://github.com/pivoshenko/pivoshenko.ai/blob/main/kasetto.yaml

Bare kst sync now resolves that URL on its own, on every machine where you drop the same two-line file. Browser URLs are rewritten here exactly as they are for --config, and private repositories authenticate the same way.

Three things still take precedence, in this order: $KASETTO_CONFIG, an explicit --config, and a ./kasetto.yaml in the current directory. That last one matters most in practice. Inside a repository that ships its own config, the persisted source: is ignored, so a global default and a project config coexist without either fighting the other.

The value does not have to be a URL. An absolute local path works too, which is useful for keeping a config outside the repositories that consume it.

Multiple Agents

The agent field accepts a single value or a list. With a list, Kasetto installs each asset into every selected agent that supports that asset type:

agent:
  - claude-code
  - cursor
  - codex
 
skills:
  - source: https://github.com/org/skill-pack
    skills: "*"

Handy when you juggle multiple agents and want them all to share the same skill set.

Agent vs Destination

If you set both, destination wins. Use agent for convenience with supported presets, or destination when you need full control over the install path.

Scope: Global vs Project

By default, skills are installed globally into the agent's home-directory path. Add scope: project to your config, or pass --project on the command line, to install into the current project directory instead.

The --project / --global flags always override whatever scope is set in the config file.

Environment Variables

These environment variables affect Kasetto's behavior:

Update Check

Once every 24 hours, Kasetto asks https://kasetto.dev/latest for the newest released version and caches the answer next to its other cache files. If a newer version exists, the next command ends with a single yellow notice. The request runs on a background thread and any failure is silent, so being offline or behind a proxy never slows a command down or breaks it.

The endpoint records the hit as an anonymous counter, which is how the project measures how many installs are actively in use. What is stored is a salted digest of the request IP and user agent, never the IP itself. The digest is stamped with the period it counts and rotates with it: the daily counter cannot be correlated beyond that day, the weekly one beyond that ISO week. Nothing identifies a machine across periods, and no raw address is ever written. Binary downloads for kst self-update still go straight to GitHub.

To opt out, set KASETTO_NO_UPDATE_CHECK to any value other than 0:

export KASETTO_NO_UPDATE_CHECK=1

No request is made and no notice is printed. kst doctor then reports the update check as not yet checked.