cp-skill-health-check
Diagnose Commonplace project layout, promoted-skill discovery, user-level uv tool installation, command PATH ownership, and launch-environment failures.
zby · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add zby/commonplace --skill cp-skill-health-check技能说明
name: cp-skill-health-check description: Diagnose Commonplace project layout, promoted-skill discovery, user-level uv tool installation, command PATH ownership, and launch-environment failures. type: kb/types/instruction.md user-invocable: true allowed-tools: Read, Grep, Glob, Bash context: fork argument-hint: "[symptom] — optional description of what is broken"
Commonplace Health Check
EXECUTE NOW
Use this skill when a Commonplace KB has missing skills, missing or failing commonplace-* commands, or commands that work in one shell but not in an IDE or agent runtime. It applies both to installed KBs, where shipped content lives under kb/commonplace/, and to the Commonplace source repository, where shipped content lives directly under kb/.
Target symptom: $ARGUMENTS
Do not modify files during diagnosis. Report the evidence and the smallest repair. Apply a repair only when the user asked for one.
Step 1 — Locate the project and classify the layout
From the workspace root, inspect:
pwd
test -f AGENTS.md && echo "AGENTS.md: present" || echo "AGENTS.md: missing"
test -f CLAUDE.md && echo "CLAUDE.md: present" || echo "CLAUDE.md: missing"
test -d kb/commonplace && echo "layout: installed KB" || true
test -f pyproject.toml && test -d src/commonplace && echo "layout: source repo" || true
test -d .agents/skills && echo ".agents/skills: present" || true
test -d .claude/skills && echo ".claude/skills: present" || true
Interpretation:
- Installed KB:
kb/commonplace/{notes,reference,instructions}/exists. - Source repository:
pyproject.toml,src/commonplace/, and top-levelkb/{notes,reference,instructions}/exist. - Neither: the wrong directory is open or
commonplace-inithas not run. .venvis not a Commonplace layout requirement. A project may still own one for unrelated dependencies.
Step 2 — Check the control plane and skill projections
Read the active root control-plane file and confirm it routes Commonplace commands by bare name. Then inspect the canonical health skill and the runtime projections:
test -f kb/commonplace/instructions/cp-skill-health-check/SKILL.md && echo "installed canonical skill: OK" || true
test -f kb/instructions/cp-skill-health-check/SKILL.md && echo "source canonical skill: OK" || true
test -f .agents/skills/cp-skill-health-check/SKILL.md && echo ".agents projection: OK" || true
test -f .claude/skills/cp-skill-health-check/SKILL.md && echo ".claude projection: OK" || true
If the canonical skill exists but the current runtime cannot discover its projection, commonplace-init may need to be rerun or the runtime may use another skill-discovery surface. Do not repair a Commonplace source checkout with commonplace-init; follow the source repository's AGENTS.md instead.
Step 3 — Check the uv tool installation and command ownership
On Linux/macOS:
command -v uv || true
uv tool list || true
uv tool dir --bin || true
command -v commonplace-init || true
command -v commonplace-validate || true
which -a commonplace-validate 2>/dev/null || true
On native Windows PowerShell:
Get-Command uv -ErrorAction SilentlyContinue
uv tool list
uv tool dir --bin
Get-Command commonplace-init -All -ErrorAction SilentlyContinue
Get-Command commonplace-validate -All -ErrorAction SilentlyContinue
Classify the result:
- uv missing: the installation prerequisite is absent.
llm-commonplaceabsent fromuv tool list: the user-level tool is not installed.- Command exists inside
uv tool dir --binbut bare-name lookup fails: the tool executable directory is missing from this process'sPATH. - Bare name resolves outside
uv tool dir --bin: another install or a project venv shadows the user-level tool. Report every candidate fromwhich -aorGet-Command -All. - Only some declared
commonplace-*commands exist: the tool installation is incomplete or stale after an entry-point metadata change; reinstall it. - A fresh terminal resolves the command but the IDE or agent does not: the launch class did not inherit the updated user environment. Treat this as runtime environment propagation, not package absence.
Do not use uv tool install --force as the default repair for an executable conflict. First identify which installation owns the conflicting name and remove or reorder the stale owner.
Step 4 — Check legacy project-environment residue
Inspect only; do not delete:
test -f .envrc && sed -n '1,80p' .envrc || true
test -d .venv && echo ".venv exists; determine its owner before cleanup" || true
The exact .envrc generated by older Commonplace releases contained only:
export PATH="$PWD/.venv/bin:$PATH"
export UV_CACHE_DIR="$PWD/.uv-cache"
That exact file is obsolete after the user-level tool works in fresh processes. An edited .envrc must be reviewed manually. A .venv may hold the project's own dependencies; never classify it as removable merely because Commonplace no longer needs it.
Step 5 — Check package and validator health
If this is an installed KB:
commonplace-validate kb/commonplace/reference/commands.md
If this is the Commonplace source repository:
commonplace-validate kb/reference/commands.md
uv run pytest -q
Interpretation:
- Command not found: return to step 3.
- Import or dependency error: reinstall the uv tool. For an editable source install, metadata and dependency changes require
uv tool install --reinstall --python ">=3.11" --editable .even though ordinary source edits do not. - Validator runs: the command package is healthy; focus on skill discovery or launch-environment propagation.
uv run pytestfails before tests start: the source project's dependency environment is unhealthy.pytestis a development dependency, not part of the Commonplace command tool.
Repair commands
Published install:
uv tool install --python ">=3.11" llm-commonplace
uv tool
阅读完整来源 ↗