#Manifest

skills-package-manager uses skills.json as the single user-maintained configuration file.

#skills.json

skills.json describes which skills a project needs, where they should be installed, and which agent directories should receive symlinks.

{
  "installDir": ".agents/skills",
  "linkTargets": [".claude/skills"],
  "selfSkill": false,
  "patchedSkills": {
    "find-skills": "patches/find-skills.patch"
  },
  "skills": {
    "find-skills": "github:vercel-labs/skills#abc1234&path:/skills/find-skills",
    "my-linked-skill": "link:./local-source/skills/my-linked-skill",
    "my-existing-skill": "local:*",
    "my-packed-skill": "file:./skills-package.tgz&path:/skills/my-packed-skill",
    "my-npm-skill": "npm:@scope/skills-package@1.0.0&path:/skills/my-npm-skill"
  },
  "dependencies": {
    "shared-helper": "github:owner/repo#def5678&path:/skills/shared-helper"
  }
}

Field descriptions:

• installDir: The directory where managed skills are written.
• linkTargets: Target directories where symbolic links should be created.
• selfSkill: Whether to auto-install the bundled skills-package-manager-cli skill during install. Defaults to false.
• patchedSkills: Optional mapping from skill name to a committed patch file path.
• skills: A mapping from skill name to specifier.
• dependencies: A generated lock mapping for dependencies discovered from installed skills' SKILL.md frontmatter.

Skills can declare dependencies in top-level frontmatter:

---
name: workflow-skill
dependencies:
  shared-helper: "github:owner/repo#main&path:/skills/shared-helper"
---

Dependency specifiers use the same syntax as skills.json. If skills.json.dependencies already contains the dependency name, that manifest entry is used as the source and re-pinned after a successful install.

#Pinning Model

Remote versions are pinned in skills.json:

• add resolves git refs to commits and npm packages to versions before writing the manifest.
• install discovers recursive frontmatter dependencies, writes their resolved pins into dependencies, and prunes stale dependency locks after a successful install.
• update without arguments moves root skills and dependency locks to the latest resolvable git or npm version; named updates only target root skills.
• No separate lock file is written.

#Recommended Practices

1. Commit skills.json.
2. Ignore generated skill directories such as .agents/skills and .claude/skills.
3. Prefer explicit github: or git specifiers with path: for external skills.
4. Use local:* for existing user-owned skills that live under ${installDir}/${skillName}.