dev-skills

Appearance

Use dev-skills in a repo ​

How to consume @chriscalo/dev-skills from another repository: run its tools, read its skills from local disk, and keep both up to date. The preferred method is the package, because it is the only one that delivers the runnable tools and pins a version per repo. A lighter content-only option is noted at the end.

The package is private. It is published to GitHub Packages, not the public npm registry, and installed with npm. Everything below assumes you can read the chriscalo/dev-skills repo and its GitHub Packages.

What you get ​

  • The tools, behind one umbrella CLI: dev-skills <command> (lint, the issue dashboard, PR-comment fetch, spec and eval, and more). See Run the tools.
  • The skills on disk, symlinked into your agent dirs so they auto-load by context, with an AGENTS.md pointer as a universal fallback. See Reference skills locally.
  • Versioned updates, propagated by Dependabot as small bump PRs you adopt on your schedule. See Keep it up to date.

1. Authenticate to GitHub Packages ​

GitHub Packages is a private registry, so npm needs a token to read it. Commit a token-free .npmrc that scopes the @chriscalo namespace to the registry and reads the token from an env var:

ini
# .npmrc (committed; no token in the file)
@chriscalo:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Then supply NODE_AUTH_TOKEN per environment:

  • Local dev: put a read:packages personal access token in your user~/.npmrc (never the repo), or export NODE_AUTH_TOKEN in your shell.

    ini
    # ~/.npmrc (personal, not committed)
//npm.pkg.github.com/:_authToken=<your read:packages PAT>

  • CI: the built-in GITHUB_TOKEN works once the package grants the repo read access (see Keep it up to date). Give the job packages: read and pass the token to setup-node:

    yaml
    permissions:
  contents: read
  packages: read
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: "20"
      registry-url: "https://npm.pkg.github.com"
      scope: "@chriscalo"
  - run: npm ci
    env:
      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2. Install the package ​

sh
npm install --save-dev @chriscalo/dev-skills

Keep it on a caret range ("@chriscalo/dev-skills": "^1.0.0") so patches and minors flow in automatically and majors arrive as their own PR.

3. Activate the skills ​

Installing runs a postinstall hook that symlinks the skills into your repo's agent dirs automatically, so adding the dependency is usually enough. It writes .agents/skills/ always, and .claude/skills/ when a .claude/ dir exists, and gitignores those targets. It is idempotent.

Run it explicitly when the hook was skipped or you want to wire the auto-update config at the same time:

sh
npx dev-skills install        # symlink skills + scaffold auto-update wiring

When to run it by hand:

  • --ignore-scripts environments. Some CI and orgs disable lifecycle scripts, so npm skips postinstall. Run npx dev-skills install (or add it to your own prepare script) to activate skills there.
  • After a major or a skill add/remove. Re-run it so symlinks reflect added or removed skills. Edits to existing skills need no re-run; the symlink already points at the updated file.

Flags: --all writes every known agent dir regardless of markers; --force overwrites a conflicting file or link.

4. Run the tools ​

Everything is under the umbrella CLI:

sh
npx dev-skills --help              # discover commands
npx dev-skills code-style lint .   # run a leaf tool
npx dev-skills github issues       # nested: dev-skills -> github -> issues

Shortcut the commands you use often. Two supported ways, both stable across versions (command names are a versioned contract):

  • npm script (travels with the repo, so every contributor and agent gets it):

    json
    {
  "scripts": {
    "lint": "dev-skills code-style lint ."
  }
}

  • Shell alias for interactive use: alias lint='dev-skills code-style lint'.

5. Point your AGENTS.md at the skills ​

Add a pointer so any agent, even one with no symlink support, can find the skills on local disk. Paste this into the consuming repo's AGENTS.md (or CLAUDE.md):

md
## Skills

This repo uses `@chriscalo/dev-skills`. Read skills from local disk; do not
fetch the website. Find a skill's path with `npx dev-skills path <skill>`, e.g.
`npx dev-skills path git`. The skills are also symlinked under `.agents/skills/`
(and `.claude/skills/` when present).

6. Reference skills locally ​

The skills land on disk, so an agent reads them without the website or a network:

sh
npx dev-skills list                       # list available skills
cat "$(npx dev-skills path git)/git.md"   # read a topic from disk

The symlinks under .agents/skills/ and .claude/skills/ are what make skills auto-load by context. The AGENTS.md pointer covers agents whose project-local skill dir is not yet supported.

One level per agent. If you pin dev-skills at the project level (.claude/skills/) while also having it globally in ~/.claude/skills/, the personal copy wins on a name clash and defeats per-repo version pinning. Pick one level per agent.

Keep it up to date ​

Updates propagate as Dependabot bump PRs. Two one-time pieces:

  1. Grant the repo read access (done on the package, once per repo). In the @chriscalo/dev-skills package settings, under Manage Actions access, add this repo (or the whole account) with the Read role. Dependabot then authenticates to GitHub Packages with its own GITHUB_TOKEN; there is no PAT, no Dependabot secret, and no registries: block to add.

  2. Scaffold the bump config (done by the install step). dev-skills install (or dev-skills scaffold) writes three committed files, skipping any that already exist:

    • .github/dependabot.yaml: tells Dependabot to watch npm deps weekly.
    • .github/workflows/dev-skills-adopt-major.yaml: on a major bump, asks your coding agent to apply the shipped migration to the PR branch (see below).
    • .github/workflows/dev-skills-automerge.yaml: opt-in, default off, auto-merges patch and minor bumps once CI is green.

    Commit them.

With those in place and the dependency on a ^ range, Dependabot files a bump PR whenever a new version publishes; your CI runs and merging adopts the update.

Auto-merging patch and minor bumps (opt-in) ​

Patch and minor bumps are non-breaking by construction (see packages-versioning), so you can let them merge themselves once you trust the pipeline. It is off by default. To turn it on, set the repo variable DEV_SKILLS_AUTOMERGE to true (Settings > Secrets and variables > Actions > Variables). It requires auto-merge enabled in repo settings and branch protection that requires your CI checks, so a check that quietly got stricter goes red and blocks the merge. Leave it off for a repo with thin or no CI, where green would mean nothing. Majors never auto-merge.

Adopting a major (hands-off, then you review) ​

A major bump arrives as its own PR. The scaffolded dev-skills-adopt-major.yaml workflow asks the Copilot coding agent to read the release's migration (node_modules/@chriscalo/dev-skills/migrations/<version>.md) and apply it to the PR branch. The PR then runs your CI and waits for your review; nothing merges automatically. You approve the result. This needs the Copilot coding agent enabled in the repo; if you use a different agent, swap the request step in that workflow.

Renovate (upgrade path) ​

Dependabot is the default and needs no third-party infrastructure. If you later want fleet-wide shared config or native auto-merge everywhere, Renovate is the documented upgrade path: install the Mend app on your account, extend one shared preset from every repo, and use Renovate's automerge option. Switching bots changes nothing else here.

Lighter option: content only, no package ​

If a repo only wants to read the skills and does not need the tools or version pinning, the global skills installer also targets a single repo:

sh
npx skills add chriscalo/dev-skills

This symlinks the skills content straight from GitHub with no .npmrc and no dependency entry. It does not deliver the runnable tools and has no lockfile or SemVer pin, so it is not the preferred method; use the package for anything beyond reading skills.

See also ​