Skill anatomy

Skills follow the open Agent Skills shape: a directory with a SKILL.md file and optional resource folders.

On disk (after pm-skills pull)

.claude/skills/secure-coding-policy/
  SKILL.md
  scripts/…          # optional
  references/…       # optional
  assets/…           # optional

The same skill may also be written under .agents/skills/ or .github/skills/ depending on agent detection.

SKILL.md

YAML frontmatter + Markdown body. Typical frontmatter fields:

Field	Role
name	Kebab-case id (validated)
description	What the skill does and when to use it
license	Optional
compatibility	Optional agent/tool hints
allowed-tools	Optional tool allowlist
metadata	Includes provenance after sync (pm_skill_id, pm_version_sha, …)

The body is the progressive-disclosure instructions your agent reads when the skill applies.

Provenance

When pm-skills materializes a skill, it injects Instructions Manager metadata into frontmatter (for example pm_skill_id, pm_version_sha, pm_scope, pm_synced_at). That is how status detects managed skills vs hand-written local skills, and how prune avoids deleting folders the CLI did not create.

Bundles

Versions can attach resource files (scripts, references, assets) stored with the version. pull downloads them via the bundle endpoint into the skill directory.

Spec validation

The server validates name regex, description length, and body size guidelines on create/update. Prefer keeping bodies focused — large skills should point at references/ instead of inlining everything.