Dependencies between items

Items in a source can reference siblings via {{ns:name}} tokens (see Namespaces and references) and path tokens like {{tools:name}}. Those tokens are dependency edges. When you install a partial selection, mind follows those edges to the full transitive closure so you get a working set, not a dangling one.

What counts as a dependency

A dependency is an intra-source reference. There are two ways to declare one, and the closure that learn installs is their union.

{{ns:name}} tokens – a token appearing in a file where it expands names a sibling as a dependency. A token expands in a file when the file has a markdown extension, or the item is of the workflow kind, or the file is on the item’s expand: list. In practice that means the whole skill directory’s .md/.markdown/.mdown/.mkd files, or the agent/rule file, as before, plus a workflow’s own .js file: a {{ns:}} token there forms a dependency edge the same as one in markdown does, because the dependency scan reads exactly the files install expands, and install expands a workflow’s .js. A token in an ordinary non-markdown bundled file (a shell script, a data file) still forms no dependency edge. This is the inline form: the reference lives in the prose (or, for a workflow, the meta.name field or body) and is also rewritten to the effective name on install. See Namespaces and references for token expansion rules.

requires: frontmatter key – a top-level scalar in the item’s frontmatter (SKILL.md for a skill, the .md for an agent or rule), listing whitespace-separated intra-source refs:

---
description: My skill
requires: skill:plan agent:test
---

This is the pure-metadata form: it adds a dependency edge without any prose reference. Use it when an item needs a sibling at runtime but does not mention it in its text.

Each entry is either a qualified ref (kind:name, e.g. skill:plan) or a bare name. A bare name matches across kinds; if more than one sibling shares that bare name across different kinds, the ref is ambiguous and must be qualified. A source-qualified ref (owner/repo#name) is rejected – requires is intra-source only. An entry that resolves to no sibling (typo, unknown item, ambiguous bare name, or source-qualified ref) is a hard error at install.

Path tokens: {{tools:name}}, {{resources:name}}, and {{path:kind:name}} are dependencies on the tool, resource, or item they name, under the same expansion rule as {{ns:}}. A bare {{path:name}} depends on the one sibling with that name; if several kinds share it, install rejects the token as ambiguous. {{self}} names the item itself and is not a dependency. See Share helper scripts and Share data files.

Dependencies never cross sources; tokens and requires: entries are always resolved within the one source.

One consequence: an item link offers a single item (a skill, or – for a file link – an agent, rule, or command), so a reference to a sibling has nothing to resolve against. A requires: entry there is dropped and the item still installs; the drop is warned about and recorded, so mind recall <item> and mind introspect show it afterwards. A token ({{ns:}}, {{tools:}}, {{path:}}) is an error, since it is rewritten into the item’s text. Both point at the same kind-qualified remedy: mind unmeld <identity> --yes && mind meld <repo-url> --learn '<kind>:<name>' --yes (adding --add-root <dir> before --learn when the repo’s own inventory does not declare the item). For a file link whose parent directory is not its kind’s container, no whole-repo meld can reach the item at all, so no command is printed; see Item links for that case and the full command for every other form.

Partial learn pulls in the closure

When learn selects every item in a source (e.g. learn owner/repo#*), resolution is a no-op: every referent installs anyway. The work is for a partial selection.

Example: a source ships skill:review, agent:dev, and agent:test. review references dev via {{ns:dev}}, and dev references test via {{ns:test}}.

mind learn skill:review

mind resolves the closure – review -> dev -> test – and installs all three, dependencies first.

What you see before install

When the closure adds items beyond your explicit selection, mind prints the dependency tree and prompts before changing anything:

skill:review  [selected]
  agent:dev   [dependency]
    agent:test  [dependency]

Install these 3 items? [y/N]

Nodes already in the manifest are marked [installed] and are not re-installed. Cycles are shown as marked back-edges rather than expanded again.

--yes (or answering y) confirms without prompting. Under --json there is no prompt at all: --yes is mandatory whenever the closure adds items beyond the explicit selection, and learn --json without it refuses with confirmation-required instead of installing unprompted. See Commands for the full flag reference.

--dry-run preview

--dry-run renders the same dependency tree and lists the full closure that would be installed, then exits without installing anything:

mind learn --dry-run skill:review

In the terminal UI

Choosing to install an available item in mind probe shows the same dependency tree in the confirm step before applying, with the same selected / dependency / already-installed distinction. Confirming installs the whole closure in dependency-first order; declining installs nothing.

forget does not cascade

forget removes exactly the one named item. It does not automatically remove its dependencies, because a dependency may be shared by another installed item. Uninstall is always a per-item operation.