skillpm copilot-instructions.md

Copilot Instructions for skillpm

What is skillpm?

skillpm is npm for Agent Skills. It builds on top of npm to add skill-awareness: resolving skill dependency trees, scanning for installed skills, and wiring them into agent directories.

Design principle: stay as close to npm as possible. skillpm should feel like npm. Same package.json, same node_modules, same package-lock.json, same registry. skillpm only adds what npm cannot do by itself: discovering installed skills and linking them into agent directories.

skillpm only manages npm-hosted skills. For broader project-level agent packaging or non-npm sources, point users to APM or to the underlying host-specific tools.

The project is developed in TypeScript.

Key dependencies (don't reimplement — use these)

Package	Type	What it does	How skillpm uses it
npm	CLI (shell out)	Package management, dependency resolution, registry, lockfiles, caching	All package operations — skillpm install calls npm install under the hood
skills	CLI (shell out)	Links skills into agent directories	npx skills add <path> — wires npm-installed skills into agent dirs
skills-ref	CLI (shell out)	Validates SKILL.md against the Agent Skills spec	npx skills-ref validate <path> during skillpm publish

Before writing any new code, check whether one of these tools already does it.

What are Agent Skills?

Agent Skills are modular, reusable packages of instructions, scripts, and resources that AI agents can dynamically load to extend their capabilities. They follow an open standard adopted by Claude, Codex, Cursor, Gemini CLI, Augment, and others.

Skill package structure

A skill is a standard npm package with the skill content in a skills/<name>/ subdirectory:

my-skill/
├── package.json                 # npm metadata, deps, keywords: ["agent-skill"]
├── README.md
├── LICENSE
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── scripts/
        ├── references/
        └── assets/