skm

Bring agent skills under control for team projects

Pin the exact skills a repo expects, materialize them into the agent directory, and keep local aliases consistent across skill authors.

npx @stefafafan/skm init

project/

project/
|-- skills.json
|-- skills.lock.json
`-- .agents/skills/
    |-- commit-message-writer/
    |   `-- SKILL.md
    |-- gha-pinner/
    |   `-- SKILL.md
    `-- web-security-reviewer/
        `-- SKILL.md

team setup

$ skm init
$ skm add stefafafan/skills
$ skm rename pin-github-actions gha-pinner
$ git add skills.json skills.lock.json

skills.json

{
  "outputDir": ".agents/skills",
  "skills": {
    "gha-pinner": {
      "source": "https://github.com/stefafafan/skills/tree/main/skills/pin-github-actions",
      "requested": "main",
      "strategy": "wrap"
    }
  }
}

Manifest + lockfile

Managed inventory

skills.json records team intent, skills.lock.json pins the resolved revision, and .agents/skills stays derived output instead of an unmanaged directory.

skills.json

The project manifest says what should exist and where skm should install it.

{
  "outputDir": ".agents/skills",
  "skills": {
    "gha-pinner": {
      "source": "https://github.com/stefafafan/skills/tree/main/skills/pin-github-actions",
      "requested": "main",
      "strategy": "wrap"
    }
  }
}

skills.lock.json

The lockfile records the exact upstream commit used for each installed skill.

{
  "skills": {
    "gha-pinner": {
      "resolved": "7c0a0ace496d1811f06a5c63fe46ed2fb4fc6437",
      "integrity": "sha256-8c57e4f6f4e1e2d9b6b7c8a9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9"
    }
  }
}

Agent directories

Any agent, same workflow

Works with any agent that reads skills from a directory.

Example: Claude

init

skm init --output-dir .claude/skills

skills.json

{
  "outputDir": ".claude/skills",
  "skills": {
    "gha-pinner": {
      "source": "https://github.com/stefafafan/skills/tree/main/skills/pin-github-actions"
    }
  }
}

Example: Windsurf

init

skm init --output-dir .windsurf/skills

skills.json

{
  "outputDir": ".windsurf/skills",
  "skills": {
    "gha-pinner": {
      "source": "https://github.com/stefafafan/skills/tree/main/skills/pin-github-actions"
    }
  }
}

Comparison

Consistent Skill Names

Move from hand-edited skill folders to a reviewable setup where names and installed skills stay consistent.

No skm

Manual copies drift and naming depends on the taste of the skill author.

project/
`-- .agents/skills/
    |-- commit-msg-helper/
    |   `-- SKILL.md
    |-- stefans-best-skill/
    |   `-- SKILL.md
    |-- infra-master/
    |   `-- SKILL.md
    `-- ultra_fast_coder_skill/
        `-- SKILL.md

With skm

The manifest owns installation and aliases, so every machine converges on the same names.

project/
|-- skills.json
|-- skills.lock.json
`-- .agents/skills/
    |-- commit-message-writer/
    |   `-- SKILL.md
    |-- gha-pinner/
    |   `-- SKILL.md
    `-- web-security-reviewer/
        `-- SKILL.md

Start

Just give it a try

Try skm via npx or take a look into the repository

npx @stefafafan/skm init