feat(skills): add skills-lock.json workflow, remove Makefile installer - #175
Conversation
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe PR replaces Makefile-based skill installation with Bun scripts and a committed ChangesSkills management workflow
MCP configuration formatting
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@rules/skills-management.md`:
- Around line 3-12: Update the CLI reference in the skills-management
documentation to link to the skills CLI repository, matching the repository-root
link used by README.md instead of issue 549. Add the text language identifier to
the fenced SKILLS.txt example while preserving its contents.
In `@scripts/skills-lock.ts`:
- Around line 19-27: Update the global lock loading flow before the
installed-skills iteration: check the lock path, handle missing files and JSON
parse failures, and validate that globalLock.version and globalLock.skills are
present before calling Object.entries. On any invalid or absent lock, exit with
a clear message directing the user to initialize the CLI lock instead of
allowing an unhandled exception.
In `@skills-lock.json`:
- Around line 1-20: Update each skill entry in skills-lock.json with a resolved
commit SHA in its ref field, and ensure scripts/skills-install.ts uses that ref
when installing sources so locked skills are reproducible rather than following
the default branch; if head tracking is intentional instead, document that
policy explicitly in the lock format or installation flow.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 3104be0e-54a7-44ba-8d8e-4b3bd3e2194f
⛔ Files ignored due to path filters (1)
bun.lockis excluded by!**/*.lock
📒 Files selected for processing (8)
.ruler/mcp.jsonMakefileREADME.mdpackage.jsonrules/skills-management.mdscripts/skills-install.tsscripts/skills-lock.tsskills-lock.json
| { | ||
| "version": 3, | ||
| "skills": { | ||
| "add-adapter": { | ||
| "source": "vercel/chat", | ||
| "sourceType": "github", | ||
| "sourceUrl": "https://github.com/vercel/chat.git" | ||
| }, | ||
| "agent-browser": { | ||
| "source": "inference-sh/skills", | ||
| "sourceType": "github", | ||
| "sourceUrl": "https://github.com/inference-sh/skills.git" | ||
| }, | ||
| "agent-ci": { | ||
| "source": "redwoodjs/agent-ci", | ||
| "sourceType": "github", | ||
| "sourceUrl": "https://github.com/redwoodjs/agent-ci.git", | ||
| "skillPath": "skills/agent-ci/SKILL.md", | ||
| "skillFolderHash": "74743678978f58979faaae7fc71c24a7e9a245b9" | ||
| }, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🌐 Web query:
vercel-labs skills CLI add pin ref commit lockfile
💡 Result:
The Skills CLI (by vercel-labs/skills) manages reusable instruction sets for AI coding agents [1][2]. While standard usage involves installing skills via npx skills add <source> [3][4], the system includes lockfile mechanisms to track versions and ensure deterministic installations [5][6]. Key concepts regarding pinning, commits, and lockfiles include: Pinning via Refs You can pin skills to specific versions by appending a reference (ref) to the source string [7]. The CLI supports using branches, tags, or commit SHAs as suffixes [7]: npx skills add owner/repo@v1.0.0 # Pin to a tag [7] npx skills add owner/repo@abc1234 # Pin to a commit SHA [7] npx skills add owner/repo@main # Pin to a branch [7] Lockfile System The CLI maintains state tracking via lockfiles [6]. When a skill is added to a project (non-globally), the CLI automatically updates a local lockfile (skills-lock.json), which records metadata about the installed skill, including the source, the reference (tag, branch, or SHA), and the commit SHA [5][7][6]. Lockfile Features and Commands Recent enhancements to the CLI have introduced more robust lockfile management [5]: - Lockfile Verification: The skills verify command allows you to check if installed files match the hashes recorded in your lockfile [5]. - CI Integrity: The skills ci command (and the --frozen-lockfile flag) can be used to ensure that installations are consistent with the existing lockfile, failing if discrepancies are found [5]. - Commit SHA Tracking: The system captures and stores the HEAD commit SHA at the time of installation, providing traceability for the exact version of the skill code in use [5][7]. For project-level installs, these lockfiles are intended to be committed to version control, ensuring the entire team uses the exact same versions of the skills [7][3].
Citations:
- 1: https://vercel-labs-skills.mintlify.app/
- 2: https://vercel-labs-skills.mintlify.app/introduction
- 3: https://vercel-labs-skills.mintlify.app/quickstart
- 4: https://vercel-labs-skills.mintlify.app/installation
- 5: feat: Lockfile Enhancements (ci, verify, commit SHA pinning) vercel-labs/skills#500
- 6: https://deepwiki.com/vercel-labs/skills/4.1-add-install
- 7: [RFC] Versioning vercel-labs/skills#11
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'files matching skills-lock/skills-install/skills-management/rules:\n'
git ls-files | rg '(^skills-lock\.json$|scripts/skills-lock\.(ts|js|tsx|jsx)$|scripts/skills-install\.ts|rules/skills-management\.md)$' || true
printf '\nlock top entries ref/source/hash pattern:\n'
if [ -f skills-lock.json ]; then
wc -l skills-lock.json
python3 - <<'PY'
import json
p='skills-lock.json'
data=json.load(open(p))
skills=data.get('skills',{})
for name, cfg in skills.items():
print(name, {
'source': cfg.get('source'),
'ref': cfg.get('ref'),
'skillPath': cfg.get('skillPath'),
'skillFolderHash': cfg.get('skillFolderHash'),
'hasAllHashes': 'skillFolderHash' in cfg and 'skillGitHash' in cfg
})
print('count ref present:', sum(1 for cfg in skills.values() if 'ref' in cfg))
print('count skillFolderHash present:', sum(1 for cfg in skills.values() if 'skillFolderHash' in cfg))
print('count skillGitHash present:', sum(1 for cfg in skills.values() if 'skillGitHash' in cfg))
PY
fi
for f in scripts/skills-install.ts scripts/skills-lock.ts rules/skills-management.md; do
if [ -f "$f" ]; then
printf '\n=== %s (%d lines) ===\n' "$f" "$(wc -l < "$f")"
sed -n '1,220p' "$f"
fi
doneRepository: shunkakinoki/dotagents
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
for f in scripts/skills-install.ts scripts/skills-lock.ts rules/skills-management.md; do
printf '\n=== %s (%d lines) ===\n' "$f" "$(wc -l < "$f")"
sed -n '1,240p' "$f"
done
printf '\nref/frozen/verify hash references:\n'
rg -n "ref|frozen|hash|skillFolderHash|skillGitHash|verify" packages scripts rules skills-lock.json || trueRepository: shunkakinoki/dotagents
Length of output: 14087
Pin skill sources before installing.
skills-lock.json has no per-skill ref, and scripts/skills-install.ts only appends #<ref> when it is present. This installs missing skills from the repository’s current default branch, so reproducing the same commit at a later date can install different skill content. Record the resolved commit SHA as ref, or document that this lock tracks upstream heads.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills-lock.json` around lines 1 - 20, Update each skill entry in
skills-lock.json with a resolved commit SHA in its ref field, and ensure
scripts/skills-install.ts uses that ref when installing sources so locked skills
are reproducible rather than following the default branch; if head tracking is
intentional instead, document that policy explicitly in the lock format or
installation flow.
There was a problem hiding this comment.
Not adopting SHA pinning for now: the upstream CLI's own lock does not record commit SHAs (it's an open request in vercel-labs/skills#549), and skills-lock.json mirrors the CLI-resolved metadata so skills update keeps working. Will revisit once upstream records SHAs in its lock.
🤖 Addressed by Claude Code
There was a problem hiding this comment.
@shunkakinoki, understood. The current lock format intentionally mirrors the upstream skills CLI lockfile to preserve skills update compatibility. SHA pinning remains dependent on upstream support in vercel-labs/skills#549.
Would you like me to create a follow-up GitHub issue to track reassessment after upstream adds commit SHA support?
✏️ Learnings added
Learnt from: shunkakinoki
Repo: shunkakinoki/dotagents PR: 175
File: skills-lock.json:1-38
Timestamp: 2026-08-02T06:43:13.982Z
Learning: In the skills-management workflow, `skills-lock.json` intentionally mirrors the metadata written by the upstream `skills` CLI. The upstream CLI lockfile does not currently record resolved commit SHAs, tracked upstream in vercel-labs/skills#549. Do not recommend adding per-skill SHA `ref` fields until upstream supports them, because preserving compatibility with `skills update` is required.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
You are interacting with an AI system.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 9 files
Not reviewed (too large): skills-lock.json (~2,279 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic
There was a problem hiding this comment.
All reported issues were addressed across 8 files (changes from recent commits).
Not reviewed (too large): skills-lock.json (~2,461 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
1 participant
What
Implements the lock-file approach from vercel-labs/skills#549 for external skills, replacing the old SKILLS.txt reconciler with a committed lock file.
SKILLS.txtstays the canonical declaration (repo + comma-separated selection; no selection = all)skills-lock.json(new, committed) is generated from SKILLS.txt viamake skills-lock: installed skills carry resolved metadata (sourceUrl,skillPath,skillFolderHash) from the global CLI lock; not-yet-installed skills get minimal source entriesmake skills-installrestores from the lock, npm-ci style: skips skills already in~/.agents/skills(no reinstalls, no network), groups the rest by source, runsbun x skills add <source> --global --yes --skill ..., non-zero exit on failure;make skills-refreshforces a reinstallmcp-sync) — no standalone scriptsskills-install(old 140-line SKILLS.txt reconciler with manifest/state dirs),skills-clean,skills-managed-clean,skills-install-repo;make syncstill callsskills-install.skills-sync/ruler-skills-copy(local repo skills) are untouchedgke-cost→gke-cost-analysis/-optimization, mattpocockto-prd/to-issues→to-spec/to-tickets, better-authcreate-auth-skill→create-auth), deletions (PaulRBergbiome-js/code-simplify/md-docs, awesome-copilotmy-issues/my-pull-requests), dead repo (better-context/skills), andvercel-sandbox(needs--full-depth)rules/skills-management.mddocuments the workflow;skills@^1.5.20pinned as devDependency (1.5.21 blocked by the 7-dayminimum-release-age; also fixesbun x skillsresolving a stale cached v0.1.0)Why
The CLI's
experimental_installonly supports project scope; this repo installs skills globally, so the Makefile scripts the global equivalent of the proposedskills install -g. The lock replaces manifest/state-dir bookkeeping with a single committed artifact that works on fresh machines and CI. Once upstream shipsskills install -g, the recipes can be swapped for it.Reviewer notes
make skills-lockoutput is stable (regenerating produces no diff) andmake skills-installis an instant no-op when converged--forcethe exit code is used since directories pre-exist.ruler/mcp.jsondiff is biome formatting only🤖 Generated with Claude Code