| name | update-project-skill |
| description | Regenerate project-skill/SKILL.md from current codebase. Triggers when project skill is stale (>24h), before context compacts, after major findings, or on first run. Also on "refresh project knowledge", "更新项目知识".
|
| disable-model-invocation | true |
Update Project Skill
Refreshes .claude/skills/project-skill/SKILL.md by scanning the entire project.
Detect Mode
Check if .claude/skills/project-skill/SKILL.md is empty or only contains skeleton placeholder content.
- Bootstrap mode (first run / empty SKILL.md): deep scan, generate from scratch
- Update mode (existing SKILL.md): incremental update, preserve existing content
Instructions
Step 1: Spawn Opus subagent (read-only)
Use the Agent tool to spawn an Opus subagent. Provide different prompts depending on mode:
Bootstrap mode prompt (first run on existing repo):
You are initializing the project knowledge base for the first time. Do a DEEP scan:
- Project identity: Read CLAUDE.md, README.md, pyproject.toml/package.json → extract project name, description, purpose, motivation
- Architecture: Use Glob to map directory tree. Read key entry points. Identify: what does this project do? What are the main modules?
- Design decisions: Read docs/specs/, docs/archive/ → extract key architectural decisions and rejected alternatives
- Experiment history: Scan exp/*/README.md → build experiment table (ID, description, status, key finding)
- Domain papers: List docs/papers/ contents → inventory of reference material
- Prompt evolution: Scan prompts/*/CHANGELOG.md → active versions and trade-offs
- Git milestone history: Run
git log --oneline -50 → identify key milestones
- Known pitfalls: Extract from exp/*/README.md "Pitfalls" sections + any LESSONS.md or troubleshooting docs
Generate a complete SKILL.md. Mark as "v0 — auto-generated bootstrap, review recommended."
Update mode prompt (incremental refresh):
You are refreshing the project knowledge base. Do an INCREMENTAL scan:
- Read current
.claude/skills/project-skill/SKILL.md — preserve structure and user-added custom sections
- Read
exp/ for new or updated experiments since last update
- Read
prompts/ for version changes
- Run
git log --oneline -20 for recent changes
- Check
docs/ for new specs or plans
Update only sections that changed. CRITICAL constraints:
- NEVER remove entries from "Key Pitfalls & Lessons Learned" (append-only)
- NEVER downgrade experiment status ("Done" stays "Done")
- Preserve any user-added custom sections unchanged
Common output format for both modes:
Output: complete SKILL.md content with these sections:
- Project Overview & Current State (name, description, motivation, current stage)
- Architecture (code structure, data flow, key modules)
- System Cognition (core understanding: what works, what doesn't, validated hypotheses, active assumptions)
- Technical Archive (key technical decisions, parameter choices, benchmark baselines, rejected alternatives with rationale)
- Experiment History Table (exp → status → prediction → actual → key finding — include prediction calibration column)
- Prediction Calibration (prediction vs actual meta-learning: systematic biases, calibration accuracy trends)
- Engineering Lessons (APPEND-ONLY — pitfalls, debugging insights, tooling gotchas, workflow improvements)
- Active Prompt Versions & Trade-offs
- Quick Reference (commands, paths, env vars)
Step 2: Show diff to user
Show diff between current and proposed SKILL.md for approval.
In bootstrap mode, show the entire generated content.
Step 3: Write on approval
Write the updated SKILL.md.
Step 4: Append CHANGELOG
Append entry to .claude/skills/project-skill/CHANGELOG.md with date and summary.
In bootstrap mode: "Initial bootstrap — auto-generated from existing codebase"
Step 5: Update pipeline state
import json, time
state = json.load(open('.pipeline-state.json'))
state['skill_updated_at'] = int(time.time())
json.dump(state, open('.pipeline-state.json', 'w'), indent=2)
Step 6: Prompt next action
"Also run /commit-changelog? (Y/n)"
