# Skilltree

> Use the skilltree CLI to manage AI agent skill and agent dependencies. IMPORTANT — before adding, editing, or removing any skill or agent file, check if the project has a skilltree.yml (skilltree-managed). If it does, use skilltree commands and only modify local skills in their origin repo, never installed artifacts.

- **Type:** Skill
- **Install:** `agentstack add skill-imarios-skilltree-skilltree`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [imarios](https://agentstack.voostack.com/s/imarios)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [imarios](https://github.com/imarios)
- **Source:** https://github.com/imarios/skilltree/tree/main/skills/skilltree

## Install

```sh
agentstack add skill-imarios-skilltree-skilltree
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# skilltree — Dependency Manager for AI Agent Skills

Use this skill when:
- Running skilltree commands (`skilltree install`, `skilltree add`, etc.)
- Setting up a new project with skill dependencies
- Discovering skills across git repositories (`skilltree registry`, `skilltree search`)
- Troubleshooting dependency resolution or installation issues
- Managing skill versions and lockfiles
- Scanning skills for undeclared dependencies
- Setting up global dependencies (`skilltree install --global`)
- Vendoring skills for distribution (`skilltree vendor`)
- Managing install targets across coding agents (`skilltree targets`)

## Reference Routing Table

| Need | Read |
|------|------|
| Command syntax and flags | `references/commands.md` |
| Step-by-step tasks (install, upgrade, Docker, global, vendor, multi-agent) | `references/workflows.md` |

## Key Concepts

**Manifest (`skilltree.yml`)** — Declares what you want: repo URLs, version constraints, local paths, and install targets. Two groups: `dependencies` (production) and `dev-dependencies` (local only).

**Lockfile (`skilltree.lock`)** — Records what you got: resolved versions, exact commit SHAs, integrity hashes. Checked into git for reproducibility.

**Remote dependency** — Fetched from a git repo at a semver-pinned version. Cached at `~/.skilltree/cache/`.

**Local dependency** — Symlinked from a co-located path (e.g., `./skills/my-skill`). Edits reflected instantly, no reinstall loop.

**Source shorthand** — The `sources:` map aliases repo URLs or local filesystem paths. Remote sources expand to `repo:`, local sources (starting with `~/`, `/`, `./`) expand to `local:`. Deps from the same local source share a "same-origin" context for transitive resolution.

**Entity types** — Skills (directory with `SKILL.md`) and agents (single `.md` file). Skills can only depend on skills. Agents can depend on both.

**Registries** — Git repos registered globally (`~/.skilltree/config.yaml`) for skill discovery. Registries are authoring-time tools — they help find and add skills via `skilltree search` but are never in the install or resolution path. The manifest stays self-contained.

**Publishing a discoverable registry** — Registry search uses a three-tier fallback per repo, stopping at the first hit:
1. `skilltree-index.yml` at repo root — hand-curated override; only needed for `tags:` or to expose a strict subset distinct from the manifest. Generated by `skilltree registry index`. Both `skilltree-index.yml` and its predecessor `skillkit-index.yaml` are legacy — prefer the manifest-first approach below.
2. **`skilltree.yml` local entries** — the preferred approach. If your repo ships a manifest, search infers every publicly-visible local entity from it automatically. Non-standard layouts (monorepo packages, custom paths) are handled via the `path:` field you already declare on each `local:` entry.
3. Dynamic scan — last resort; only finds standard layouts (`**/SKILL.md`, agents as top-level `.md` with `name:`/`skills:` frontmatter, slash-commands under `commands/`).

**Publication surface controls** — Two optional fields on `local:` entries in `skilltree.yml` shape what consumers receive:
- `publish: false` — entity still installs into your own `.claude/` but is hidden from every consumer-facing path (registry indexing tier 2, vendor, origin-manifest lookup). Use for WIP entities not ready to share.
- `exclude: [...]` — gitignore-style globs (relative to the entity root) applied when the entity is copied during vendor or consumer install. Use to trim dev-only files (scratch dirs, raw crawl data, eval fixtures) from the published surface.

Both fields are validation errors on remote (`repo:` / `source:`) entries. See `docs/specs/publication_surface.md` for the full spec and `references/commands.md` → `skilltree registry index`.

## Origin-Manifest Resolution — Concepts Every Author and Consumer Should Know

When a repo ships a `skilltree.yml`, it becomes **self-describing**: downstream consumers (and skilltree itself) use that manifest as the authoritative map of what skills/agents the repo owns and where they live. This has concrete consequences:

**If you consume from a repo that has a `skilltree.yml`:**
- You can omit `path:` on direct deps. Origin's manifest supplies it.
  ```yaml
  dependencies:
    task-builder:
      repo: github.com/org/analysi-backend
      # no path: — skilltree reads origin's skilltree.yml and fills it in
  ```
- If you *do* declare `path:` and it matches origin's declared path, skilltree warns "you can omit this." If it differs, you'll see an override warning suggesting `force_path: true` to silence it for intentional forks.
- Transitive deps resolve automatically, even when the origin repo organizes skills at unconventional paths (e.g., `skills/source//`).
- Cross-repo transitive deps work too: if origin's manifest references a third-party repo, skilltree clones and resolves it on demand (respecting origin's version constraint).

**If you publish a repo that others will use as a skill source:**
- Your `skilltree.yml` is part of your **public contract**. Changes to `dependencies:` affect downstream consumers.
- Skills declared under `dev-dependencies:` stay private — they will never be exposed to downstream consumers. A consumer transitively needing a dev-dep gets a clear error pointing you, the upstream author, as the fix site.
- If you reorganize paths (e.g., move `skills/foo/` → `skills/src/foo/`) at a new tag, consumers pinning the old tag are unaffected; consumers pinning `*` or branches pick up the change via the lockfile.
- Name conflicts between skills you own and skills you transitively expose: the consumer's manifest always wins over origin's manifest (tier 2 beats tier 4).

**When origin's manifest doesn't apply:**
- Origin has no `skilltree.yml` → skilltree falls back to conventional paths (`skills//SKILL.md`, `agents/.md`, `/SKILL.md` at repo root). Old-school repos keep working with zero manifest authoring.
- Origin's `skilltree.yml` is malformed or doesn't declare the requested name → same fall-through.
- Origin's entry uses a `local:` path that's actually an absolute path on the author's machine (via a `source:` alias expanding to a filesystem path) → skipped silently; consumer gets the conventional probe.

**Quick mental model:** a repo with `skilltree.yml` is richer than one without. The manifest acts as an internal directory: "here's every skill I own, here's where each one lives, here's any third-party dep any of them needs." Consumers inherit that directory.

## Install Targets (Multi-Agent)

skilltree supports multiple coding agents. The `install_targets` field in `skilltree.yml` controls where skills are installed:

```yaml
install_targets:
  - claude    # → .claude/
  - codex     # → .codex/
```

Known agents: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `windsurf`. Custom paths use `./` prefix (e.g., `./my-agent`).

Manage targets with `skilltree targets {list,add,remove,detect,migrate}`. When absent, `install_targets` defaults to `[claude]`.

## Global vs Project vs Vendor

Three scopes, fully independent:

| Need | Mechanism | Install target | Committed to git |
|------|-----------|---------------|-----------------|
| Project needs a skill | `skilltree.yml` | Per `install_targets` | No (gitignored) |
| You want a skill everywhere | `~/.skilltree/global.yaml` | Per detected agents | No (personal) |
| Ship skills without upstream access | `skilltree vendor` | Single target | Yes (committed) |

**Global deps are a personal convenience, not a project dependency.** If the project *requires* a skill, put it in `skilltree.yml`. Global is for "I always want this available" — teammates don't need your global deps.

**Vendor mode is for distribution.** Copies all resolved deps as real files (no symlinks), removes them from `.gitignore`, and sets `vendor: true`. Consumers `git clone` and it works — no `skilltree install`, no upstream access needed. Vendor operates on a single target; use `--target` when multiple are configured. Fully reversible with `skilltree unvendor`.

When the same skill exists in both project and global scope, **project wins** (the agent's built-in shadowing).

## Packs — Named Groups of Dependencies

A **pack** is a named group of dependencies declared under a `packs:` section. Consumers reference a pack with a single `PackDependency` entry (`{pack: , [repo|source], [version]}`); the resolver expands it into the listed members at install time. A pack is never an entity itself — only its members become entities in `state.entities` and the lockfile.

Two reference modes, one mechanism:
- **Local pack** — defined and referenced in the consumer's own `skilltree.yml`. Referenced by `{pack: }` only.
- **Remote pack** — defined in some repo's `skilltree.yml`. Referenced with `{pack: , repo: , version: }`; pinned by the containing repo's git tag.

Pack members are **full dep entries** (with their own `repo`/`source`/`local`/`version`), not bare names — packs can compose deps from multiple repos. v1 is **all-or-nothing**: no consumer-side `exclude:` or per-member version override, and `pack:` members (nested packs) are rejected at parse time. `local:` members are valid in local packs only; remote packs must compose remote deps.

Add packs via CLI: `skilltree add  --pack [--repo  --version ]`, or use the local short-circuit (`skilltree add my-stack` with `packs.my-stack` already defined).

See `references/commands.md` → `skilltree add ` for the flag matrix and `docs/specs/packs.md` for the full spec.

## CRITICAL: Installed files are read-only

Files under `.claude/skills/` and `.claude/agents/` are installed artifacts — like `node_modules/`. They are:
- **Gitignored** — never checked into source control
- **Read-only** (chmod 444) — do not edit them in place
- **Recreatable** — `skilltree install` restores them from the lockfile

To modify a skill: edit the source (in the skill's repo or local `skills/` directory), bump the version tag, then `skilltree update`.

## CRITICAL: Modifying skills and agents

Before modifying any skill or agent, check if the project uses skilltree (`skilltree.yml` exists in the repo). If it does:
- **Only modify local skills/agents** defined in the current repo (listed with `local:` in `skilltree.yml`)
- **Never modify installed (remote) skills** — they are managed artifacts from other repos
- **To change a remote skill**, go to that skill's origin repo and modify it there
- If you are unsure whether a skill is local or remote, check `skilltree.yml` or run `skilltree list`

## Environment

skilltree delegates git authentication to the system. SSH keys, credential helpers, and `GITHUB_TOKEN` all work.

For `skilltree scan --llm`, set `ANTHROPIC_API_KEY`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [imarios](https://github.com/imarios)
- **Source:** [imarios/skilltree](https://github.com/imarios/skilltree)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-imarios-skilltree-skilltree
- Seller: https://agentstack.voostack.com/s/imarios
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.