Manage Agent Skills as project dependencies

Manifest, lockfile, and installed directory

A skill is an instruction bundle for an agent, not an XML package: it never enters xs:import or a prompt build. Declare it in the workspace-root xmlsquish.toml [skills] table. Even when invoked from a member, installation is under the workspace root .agents/skills.

[skills]
review-checks = { path = "tools/skills/review-checks" }
release-notes = { git = "https://github.com/example/agent-skills.git", tag = "v2", subdir = "release-notes" }

A local path is relative to the declaring manifest and must name the exact directory containing SKILL.md. Git can select rev, tag, or branch; no selector uses the remote default branch. Each [[skill]] lock record pins the source, the full Git commit when applicable, and a BLAKE3 digest of the entire tree. .agents/skills/<name> is the agent-visible copied projection.

Add, sync, and remove

xmlsquish add-skill review-checks --path tools/skills/review-checks
xmlsquish add-skill release-notes --git https://github.com/example/agent-skills.git --tag v2 --subdir release-notes
xmlsquish sync-skills --frozen
xmlsquish remove-skill review-checks

The add-skill name must match both SKILL.md frontmatter name and the destination directory. Run sync-skills after checkout to restore missing managed copies; --frozen requires an unchanged lockfile and no network. A local path is mutable: locked mode detects changed bytes instead of silently installing them. Use --dry-run to review the plan, --offline to forbid network, and --locked to forbid lockfile changes.

There is no bare-name skill registry: specify --path or --git. Removal affects only its declaration and unchanged managed copy, never unrelated manually installed directories.

Install xmlsquish's bundled guide

xmlsquish install-skill
xmlsquish install-skill --project
xmlsquish install-skill --project --dry-run

Without flags, this installs to $HOME/.agents/skills/prompt-squish (the user home directory on Windows). --project targets the workspace .agents/skills/prompt-squish. The guide is embedded in the executable, needs no source checkout, and does not edit xmlsquish.toml or xmlsquish.lock. Installing identical content is idempotent; --force can replace only a verified older copy owned by this installer, never an unowned or user-edited directory.

Review the trust boundary

Installation validates SKILL.md name and description, paths, and the complete tree, rejecting unsafe links and name collisions. xmlsquish does not run a skill's scripts while installing it, but an agent using that skill may read its instructions or run scripts later. Review third-party source and content first: a digest proves installed bytes match the lockfile, not that the instructions are safe.

This chapter covers project tooling, not XML namespace vocabulary. Existing XML DSL, artifact locators, and exit-code meanings remain unchanged; machine protocol 3.2 adds typed skill operations and results.