Configuration

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

1. $KASETTO_CONFIG env var
2. source: key in $XDG_CONFIG_HOME/kasetto/config.yaml
3. ./kasetto.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.

Example

# Choose an agent preset (single or multiple)...
agent: codex
# agent:
#   - claude-code
#   - cursor
 
# ...or set an explicit path (overrides agent)
# destination: ./my-skills
 
# Install scope: "global" (default) or "project"
# scope: project
 
skills:
  # Pull specific skills from a GitHub repo
  - source: https://github.com/org/skill-pack
    branch: main
    skills:
      - code-reviewer
      - name: design-system
 
  # Sync everything from a local folder
  - source: ~/Development/my-skills
    skills: "*"
 
  # Pin to a specific git tag
  - source: https://github.com/acme/monorepo
    ref: v1.2.0
    skills:
      - name: custom-skill
        path: tools/skills
 
  # Limit discovery to a nested directory inside the source
  - source: https://github.com/acme/agents
    sub-dir: plugins/swift-apple-expert
    skills: "*"
 
# MCP servers (optional)
mcps:
  # Discover all MCP files in the repo
  - source: https://github.com/org/mcp-pack
    mcps: "*"
 
  # Pick specific files from a monorepo (resolved from mcps/ dir)
  - source: https://github.com/org/monorepo
    ref: v1.4.0
    mcps:
      - github        # → mcps/github.json
      - linear        # → mcps/linear.json
 
  # Custom directory via { name, path }
  - source: https://github.com/org/other
    mcps:
      - name: my-server
        path: tools   # → tools/my-server.json

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 — mirrors skill entries:

Paths are resolved relative to the source root (or sub-dir if set); 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 agent's native settings file (e.g., .claude.json for Claude Code, .cursor/mcp.json for Cursor). See how sync works for merge behavior details.

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 repo, Kasetto uses the same token-based authentication as skill sources. See authentication for the full list of supported environment variables.

Multiple Agents

The agent field accepts a single value or a list. With a list, Kasetto installs skills to every agent's directory and merges MCP servers into every agent's settings file:

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 output behavior: