Agent skill
lockfile-doctor
Install this agent skill to your Project
npx add-skill https://github.com/stars-end/agent-skills/tree/master/lockfile-doctor
SKILL.md
lockfile-doctor
Description
Check and fix lockfile drift across Poetry (Python) and pnpm (Node.js) projects.
Use when:
- Dependency manifest changed (pyproject.toml, package.json) but lockfile not updated
- CI fails with lockfile errors ("poetry.lock out of sync", "frozen lockfile mismatch")
- User says "fix lockfile", "update lockfile", "lockfile out of sync", "regenerate lock"
Problem solved: Eliminates "Add dependency â Forget lockfile â CI fails" pattern (9/69 toil commits, 13% of analyzed toil).
Auto-Activation
This skill activates when:
- User mentions lockfile issues ("lockfile", "poetry.lock", "pnpm-lock.yaml")
- CI error messages contain lockfile-related failures
- Dependency manifests modified without corresponding lockfile updates
Implementation
The skill checks and fixes lockfiles for both Python (Poetry) and Node.js (pnpm) projects.
Check Script
#!/bin/bash
# ~/.agent/skills/lockfile-doctor/check.sh
set -e
echo "đ Lockfile Doctor - Checking lockfiles..."
ISSUES_FOUND=0
# Check Poetry lockfile (Python)
if [[ -f "pyproject.toml" ]]; then
echo ""
echo "đĻ Checking Poetry lockfile..."
if [[ ! -f "poetry.lock" ]]; then
echo "â ERROR: poetry.lock missing but pyproject.toml exists"
echo " Run: poetry lock --no-update"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
else
# Check if poetry.lock is in sync
if poetry check --lock 2>/dev/null; then
echo "â
poetry.lock is in sync with pyproject.toml"
else
echo "â ERROR: poetry.lock out of sync with pyproject.toml"
echo " Run: poetry lock --no-update"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
# Check if lockfile is staged when manifest changed
if git diff --cached --name-only | grep -q "pyproject.toml"; then
if ! git diff --cached --name-only | grep -q "poetry.lock"; then
echo "â ī¸ WARNING: pyproject.toml staged but poetry.lock not staged"
echo " Stage lockfile: git add poetry.lock"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
fi
fi
fi
# Check pnpm lockfile (Node.js)
if [[ -f "package.json" ]]; then
echo ""
echo "đĻ Checking pnpm lockfile..."
if [[ ! -f "pnpm-lock.yaml" ]]; then
echo "â ERROR: pnpm-lock.yaml missing but package.json exists"
echo " Run: pnpm install"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
else
# Check if pnpm-lock.yaml is in sync
if pnpm install --frozen-lockfile 2>/dev/null; then
echo "â
pnpm-lock.yaml is in sync with package.json"
else
echo "â ERROR: pnpm-lock.yaml out of sync with package.json"
echo " Run: pnpm install"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
# Check if lockfile is staged when manifest changed
if git diff --cached --name-only | grep -q "package.json"; then
if ! git diff --cached --name-only | grep -q "pnpm-lock.yaml"; then
echo "â ī¸ WARNING: package.json staged but pnpm-lock.yaml not staged"
echo " Stage lockfile: git add pnpm-lock.yaml"
ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
fi
fi
fi
echo ""
if [[ $ISSUES_FOUND -eq 0 ]]; then
echo "â
All lockfiles healthy!"
exit 0
else
echo "â Found $ISSUES_FOUND lockfile issue(s)"
echo ""
echo "Run: lockfile-doctor fix # to auto-fix all issues"
exit 1
fi
Fix Script
#!/bin/bash
# ~/.agent/skills/lockfile-doctor/fix.sh
set -e
echo "đ§ Lockfile Doctor - Fixing lockfiles..."
FIXED=0
# Fix Poetry lockfile
if [[ -f "pyproject.toml" ]]; then
echo ""
echo "đĻ Fixing Poetry lockfile..."
# Regenerate poetry.lock
echo "Running: poetry lock --no-update"
poetry lock --no-update
# Stage if pyproject.toml is staged
if git diff --cached --name-only | grep -q "pyproject.toml"; then
echo "Staging: poetry.lock"
git add poetry.lock
fi
echo "â
poetry.lock regenerated and synced"
FIXED=$((FIXED + 1))
fi
# Fix pnpm lockfile
if [[ -f "package.json" ]]; then
echo ""
echo "đĻ Fixing pnpm lockfile..."
# Regenerate pnpm-lock.yaml
echo "Running: pnpm install"
pnpm install
# Stage if package.json is staged
if git diff --cached --name-only | grep -q "package.json"; then
echo "Staging: pnpm-lock.yaml"
git add pnpm-lock.yaml
fi
echo "â
pnpm-lock.yaml regenerated and synced"
FIXED=$((FIXED + 1))
fi
echo ""
if [[ $FIXED -eq 0 ]]; then
echo "âšī¸ No lockfiles found to fix"
else
echo "â
Fixed $FIXED lockfile(s)"
echo ""
echo "Next: Commit changes with lockfiles included"
fi
Usage Examples
Check lockfiles before commit
lockfile-doctor check
Auto-fix all lockfile issues
lockfile-doctor fix
Agent workflow integration
When agent detects dependency manifest changes:
- Run
lockfile-doctor checkto verify sync - If issues found, run
lockfile-doctor fixto auto-regenerate - Stage lockfiles with manifest changes
- Commit together
Integration Points
Pre-Commit Hook (Optional)
Add soft warning to .git/hooks/pre-commit:
if git diff --cached --name-only | grep -E 'pyproject.toml|package.json'; then
~/.agent/skills/lockfile-doctor/check.sh || {
echo ""
echo "đĄ Tip: Run 'lockfile-doctor fix' to auto-fix"
}
fi
CI Workflow
Add fast-fail check to CI:
- name: Check Lockfiles
run: ~/.agent/skills/lockfile-doctor/check.sh
sync-feature-branch Skill Enhancement
Modify sync-feature-branch to auto-run lockfile-doctor:
Before committing:
1. Run lockfile-doctor check
2. If fails, run lockfile-doctor fix
3. Stage updated lockfiles
4. Commit with lockfiles included
Cross-Repo Deployment
This skill deploys to ~/.agent/skills/ and works across:
- â All repos (prime-radiant-ai, affordabot, any future repos)
- â All AI agents (Claude Code, Codex CLI, Antigravity)
- â All VMs (shared via Universal Skills MCP)
Success Metrics
Baseline: 9 commits (13% of toil) wasted on lockfile drift Target: <2 commits per 60-commit cycle Impact: ~1 hour/month saved
Notes
Design Philosophy:
- Non-blocking warnings (not hard failures) - CI enforces
- Auto-fix capability (not just detection)
- Cross-platform (Poetry + pnpm)
- Agent-friendly (clear messages, actionable commands)
Why not pre-commit hook?
- Multi-agent context: hooks get bypassed with --no-verify
- Skills provide flexibility: agents can invoke explicitly when needed
- CI provides hard enforcement: lockfile-doctor in CI catches issues
Complementary with:
- CI lockfile validation (hard enforcement)
- sync-feature-branch skill (workflow integration)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
toolchain-health
Validate Python toolchain alignment between mise, Poetry, and pyproject. Use when changing Python versions, editing pyproject.toml, or seeing Poetry/mise version solver errors. Invokes /toolchain-health to check: - .mise.toml python tool version - pyproject.toml python constraint - Poetry env python interpreter Keywords: python version, mise, poetry, toolchain, env use, lock, install
parallelize-cloud-work
Delegate independent work to Claude Code Web cloud sessions for parallel execution. Generates comprehensive session prompts with context exploration guidance, verifies Beads state, provides tracking commands. Use when user says "parallelize work to cloud", "start cloud sessions", or needs to execute multiple independent tasks simultaneously, or when user mentions cloud sessions, cloud prompts, delegate to cloud, Claude Code Web, generate session prompts, parallel execution, or asks "how do I use cloud sessions".
docs-create
Create epic-specific documentation skill with external reference docs. MUST BE USED for caching external docs. Fetches URLs, caches full content, uses documentation-engineer to generate cohesive summaries, and creates auto-activating skill. Use when starting work on epic that requires external documentation context (API docs, tool guides, reference materials), or when user mentions "cache docs", "external docs", "API documentation", URLs for docs, documentation needs, reference materials, knowledge caching, or epic context documentation.
railway-doctor
git-safety-guard
Installs a Git safety guard hook for Claude Code to prevent destructive Git and filesystem commands. Blocks accidental data loss from commands like 'git checkout --', 'git reset --hard', 'git clean -f', 'git push --force', and 'rm -rf'. Use this skill to set up safety rails in a new or existing repository, or globally for the agent.
beads-guard
Safe Beads workflow helper (warning-only). Use before bd sync/close/create to avoid JSONL conflicts. Ensures you are on a feature branch, up to date with origin/master, and stages Beads files cleanly with Feature-Key commits.
Didn't find tool you were looking for?