title: External skills - install and keep up to date
kind: sop
triggers
tools

Standard Operating Procedure: External skills

Use this for official / third-party Agent Skills (Cloudflare, Vercel, etc.). Do not copy those skills into the kit’s committed skills/ tree.

Ownership split

Kind	Location	Update path
Kit lifecycle / stack skills	`skills/agent-`, `lang-`, `framework-*`	PRs in this repo
Official upstream skills	Cursor user scope via `gh skill`	`kit sync`

Declared list: skills/external.lock.json.

Prerequisites

GitHub CLI v2.90+ with gh skill (gh skill --help)
Authenticated gh (gh auth status)

Install / refresh

# Install everything in the lockfile (Cursor --scope user)
kit sync --install

# Preview commands
kit sync --dry-run

# Pull upstream changes for lockfile skills in ~/.cursor/skills only
kit sync --update

--update refreshes lockfile skill names with --dir ~/.cursor/skills. It does not run gh skill update --all, which scans every agent host and the kit tree and warns on copies that were never installed via gh skill.

Optional from bootstrap:

INSTALL_EXTERNAL_SKILLS=1 ./install.sh

Add a skill to the lockfile

Find the upstream: gh skill search <term> or the vendor repo (e.g. cloudflare/skills, vercel-labs/agent-skills).
Preview: gh skill preview OWNER/REPO skills/<name>.
Append an entry to skills/external.lock.json:

{
  "id": "short-name",
  "repository": "owner/repo",
  "skill": "skills/short-name",
  "summary": "One line.",
  "pin": "latest"
}

Prefer a published version tag ("pin": "v1.2.0"). Use "pin": "latest" when the repo has no semver tags - gh skill then installs the latest GitHub release, else default-branch HEAD. Do not pin commit SHAs unless you are freezing a specific commit. Version tags are passed as refs/tags/… so they are not mistaken for SHAs. Tag pins are skipped by gh skill update until you change or drop them.

Run kit sync --install --force.

Prefer the exact path form (skills/<name>) so installs skip full-repo discovery.

Run kit verify to confirm no upstream dirs remain under kit skills/.

Why not vendor into `skills/`?

This kit is symlinked to ~/.agents. Vendoring upstream skills into skills/ freezes them in git and mixes ownership with lifecycle roles. gh skill writes provenance into frontmatter so upgrades detect real content changes.

Current defaults

Cloudflare: cloudflare, wrangler, workers-best-practices, durable-objects, agents-sdk from cloudflare/skills
Vercel: react-best-practices from vercel-labs/agent-skills

Markdown source