Dynamic Project Soul Snapshot | 动态项目灵魂快照

Writes AI_CONTEXT.md into the project root as a "dynamic soul snapshot" — capturing tech stack, recent git diffs, key decisions, active plan, and a compresse...

Security Scan

The skill's stated purpose (generating a repo-root AI_CONTEXT.md snapshot) is coherent, but the instructions insist on overriding built-in memory and encourage producing a high-density bootstrap block that could accidentally include secrets and be committed to version control — the SKILL.md lacks strong, enforceable safeguards against sensitive-data leakage.

Purpose & Capability

Name/description match the requested actions: scanning the repo and git history and writing a project-root AI_CONTEXT.md is consistent with a 'project snapshot' capability. However, the SKILL.md's explicit directive that it 'MUST override built-in memory tools' and 'Never write to MEMORY.md or ~/.claude/' is unusually prescriptive for a content-generation skill and deserves scrutiny: it tells the agent to bypass platform memory conventions rather than simply produce a file in the repo.

Instruction Scope

The runtime instructions direct the agent to scan code, directory structure, and Git history and to write a new file in the project root. Those actions are within scope for a project snapshot, but the skill also encourages generating a compact AI_BOOTSTRAP_BLOCK (high-entropy summary) and repeatedly 'self-healing' the document by rewriting it to match code. This combination increases the chance that secrets, credentials, or other sensitive data present in the repository will be included in AI_CONTEXT.md. The SKILL.md includes a truncated Security Notice advising manual review before committing, but it does not enforce or describe automatic secret redaction or safe-guards.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest install risk. The recommended installation (copy .skill into skills folder or upload via UI) is benign. No downloads or code execution artifacts are introduced by the skill manifest itself.

Credentials

The skill requests no environment variables or external credentials, which is proportionate. However, it explicitly instructs the agent to read repository files and git metadata (not declared as 'requires' because instruction-only), which can include sensitive config, tokens, or private keys. Because the skill intends to create a repository-tracked file, the potential for inadvertent exposure (committing secrets to VCS) exists and is not mitigated in the instructions.

Persistence & Privilege

always:false and user-invocable defaults are appropriate. The main concern is the SKILL.md's demand that the skill 'MUST override built-in memory tools' — that asks the agent to change its normal behavior relative to platform memory handling. While the skill does not request persistent platform-level privileges, the instruction to bypass built-in memory could increase risk if the agent is allowed autonomous invocation and broad file access.

What to consider before installing

This skill appears to do what it says (create a project-root AI_CONTEXT.md) but contains instructions that raise practical risks: it encourages overriding built-in memory and generating a compact bootstrap block that could include secrets or sensitive git info and then be committed to the repo. Before installing or running it: 1) Only run in repos where you trust all files; test in a disposable repo first. 2) Require or implement explicit secret redaction (API keys, private keys, passwords) before writing AI_CONTEXT.md. 3) Use a pre-commit hook or manual checklist to prevent committing AI_CONTEXT.md until you review it. 4) Prefer running it interactively (not autonomously) and avoid granting it blanket file-system or network access. 5) Ask the author (or inspect code, if added) for an explicit secret-detection/redaction step and for precise read/write commands the skill uses; that information would materially reduce risk and could change this assessment to benign.

<!-- ╔══════════════════════════════════════════════════════════════╗ ║ project-context-anchor • SKILL.md ║ ║ 动态项目灵魂快照 | Dynamic Project Soul Snapshot ║ ╚══════════════════════════════════════════════════════════════╝ -->

🧩 project-context-anchor

跨会话无损状态恢复 · AI-to-AI 上下文传递 · 自愈型项目文档

Lossless session recovery · AI-to-AI context relay · Self-healing project docs

---

📖 What is this? / 这是什么？

English: This skill automatically maintains an AI_CONTEXT.md file at your project root — a compressed, self-healing "soul snapshot" that captures your architecture decisions, recent git diffs, and active plan. When you start a new AI session, paste the <AI_BOOTSTRAP_BLOCK> as your first message and the new agent resumes exactly where you left off — no re-explaining, no lost context.

中文：本 Skill 自动维护项目根目录下的 AI_CONTEXT.md，作为项目的动态灵魂快照。 它分析代码库、Git 变更和会话历史，将核心决策压缩为高信息密度的 Prompt 片段。 下次开启新会话时，只需粘贴 <AI_BOOTSTRAP_BLOCK> 作为第一条消息， 新的 AI 便能从你上次中断的精确位置无缝接续 —— 无需重新解释背景，零上下文损耗。

---

🆚 vs. Claude Built-in Memory / 与 Claude 内置 Memory 的核心区别

理解这个差异，是决定是否需要本 Skill 的关键。

Claude Code 自带 memory 机制，会把项目信息写入 ~/.claude/projects/<hash>/MEMORY.md。 本 Skill 的输出 AI_CONTEXT.md 与之有本质区别：

维度	Claude 内置 Memory	AI_CONTEXT.md（本 Skill）
文件位置	~/.claude/（隐藏目录）	./（项目根目录，与代码并排）
可见性	只有 Claude Code 能读	人和任何 AI 工具都能读
格式	Claude 自由决定，不固定	固定五章节结构，格式可预期
Git 追踪	❌ 无法追踪、无法 diff	✅ 可提交、可审查、可回滚
跨工具使用	❌ 绑定 Claude Code	✅ 可粘贴给 Cursor、GPT-4、Gemini 等任意 AI
团队共享	❌ 个人私有，队友不可见	✅ git pull 即可获得完整上下文
自愈能力	❌ 不检查代码现实，可能记录过时内容	✅ 每次与代码对比，自动修正陈旧描述
Bootstrap Block	❌ 无	✅ <120 token 的冷启动指令，跨会话零损耗恢复

两者可以共存 / They complement each other

• 让 Claude Memory 继续运行：它适合处理轻量的会话级片段，比如你的个人偏好、临时笔记。
• 用本 Skill 处理项目级上下文：代码架构、关键决策、跨工具 / 跨会话 / 跨团队的上下文传递。

真正的核心价值在 Bootstrap Block：换一个全新会话、切换到其他 AI 工具、或让同事接手时， 只需把那几行粘贴进去，新 AI 立刻知道从哪里接着干——这是 Memory 永远给不了你的能力。

---

✨ Key Features / 核心特性

Feature	说明
🔍 Environment Scan	自动扫描技术栈、目录结构、Git 历史
🩹 Self-Healing	检测并剔除与当前代码矛盾的陈旧文档内容，代码即真相
⚡ Bootstrap Block	生成 <120 token 的高熵 AI 启动指令，用于冷启动新会话
🎛 Parameterizable	支持 optimizeFor / autoRepair / compress / silent 标志
🌐 VCS-agnostic	有 Git 时用 Git，无 Git 时优雅降级

---

🚀 Installation / 安装

Claude Code

# 将 .skill 文件放入项目或全局 skills 目录
cp project-context-anchor.skill ~/.claude/skills/

Claude.ai (Web / Desktop)

在 Settings → Skills → Upload 上传 .skill 文件即可。

---

💬 How to trigger / 如何触发

⚠️ 重要提示：在 Claude Code 中，由于内置 memory 工具优先级较高，模糊指令（如"存档进度"）可能被 memory 工具抢先处理，导致 Skill 未被调用。推荐始终使用明确指定 Skill 名称的方式触发。

⚠️ Important: In Claude Code, vague phrases like "save progress" may be intercepted by the built-in memory tool. Always use explicit skill-name invocation for reliable triggering.

✅ 推荐写法 / Recommended (Explicit)

# 中文 — 明确指定 Skill 名称（推荐）
使用 project-context-anchor skill 进行存档
用 project-context-anchor 存档当前进度
按照 project-context-anchor skill 写 AI_CONTEXT.md

# English — explicit skill invocation (recommended)
Use the project-context-anchor skill to snapshot this session
Run project-context-anchor skill and write AI_CONTEXT.md

🔶 模糊写法 / Implicit (may not trigger in Claude Code)

以下写法在 Claude.ai 网页版中可正常触发，但在 Claude Code 中可能被内置 memory 工具拦截：

存档当前进度 / Save my progress
我要下班了 / I'm done for today
封存这次会话 / Seal this session
token 快用完了，先存档 / We're near the token limit

---

📤 Cross-session resume / 跨会话恢复

新会话开始时，将生成的 <AI_BOOTSTRAP_BLOCK> 粘贴为第一条消息：

# 粘贴到新会话的第一条消息 / Paste as first message in new session:

PROJECT=my-app | STACK=React+FastAPI+Postgres | GOAL=fix race condition in useWebSocket cleanup
LAST_ACTION="feat: add JWT refresh endpoint"
DECISIONS=[stateless_jwt, no_redis_session]
TRAPS=[snake_case_routes, no_default_export_in_utils]
RESUME: Open `src/hooks/useWebSocket.ts` → find `cleanup` → continue unmount handler fix.
PENDING=[write_tests, update_openapi_spec]

新 Agent 读取后可立即接续工作，无需任何额外说明。

---

🗂 Output File Structure / 输出文件结构

生成的 AI_CONTEXT.md 包含五个标准章节：

1. 🚀 Project DNA        — 技术栈、架构风格、入口文件
2. 🛠 Current Status     — Git 分支、最近提交、未提交变更
3. 🧠 The Mental Model   — 关键决策、项目特有陷阱与约定
4. 📅 Active Plan        — 已完成 / 进行中 / 待办任务列表
5. ⚡ AI Bootstrap Block  — <120 token 的高密度冷启动指令

---

⚙️ Parameters / 参数说明

参数	默认值	说明
optimizeFor=performance	detail	仅保留状态类章节（2、4、5），省略架构描述
autoRepair=false	true	关闭陈旧内容自愈，保留原文档
compress=false	true	不生成 <AI_BOOTSTRAP_BLOCK>
silent=true	false	执行后只输出一行成功提示
fileName=custom.md	AI_CONTEXT.md	写入指定文件名

参数直接在对话中提及即可，例如："用 optimizeFor=performance 模式运行"

---

🔒 Self-Healing Rules / 自愈规则

代码是唯一真相，文档描述现实而非意图：

冲突类型	处理规则
文档提到的文件已被删除	移除引用，添加 ~~删除线~~ 注记
函数 / 类已改名	以代码中的实际名称覆盖文档
架构描述与目录结构矛盾	以当前目录结构为准重写
"下一步"任务已在 Git 中提交	标记 [x] DONE，移至 Recent Diff

---

🔐 Security Notice / 安全提示

⚠️ 在提交或分享 AI_CONTEXT.md 之前，请务必检查以下内容：

⚠️ Before committing or sharing AI_CONTEXT.md, always review for:

风险类型	说明	建议操作
🔑 API Keys / 密钥	Bootstrap Block 可能从 .env、配置文件或近期对话中捕获敏感字串	提交前运行 git diff 检查，或使用 git-secrets / trufflehog 扫描
🗝 Tokens / 令牌	Git 历史摘要中可能含有带 token 的 commit message	确认 Recent Diff 章节中无明文凭证
📁 私有路径	内部服务器地址、数据库连接串可能出现在架构描述中	若文件需公开共享，手动脱敏后再提交
💬 会话内容	Intent Extraction 阶段会摘录最近对话，可能含有业务敏感信息	在开放仓库中使用时，优先使用 compress=false 或 silent=true 精简输出

推荐做法 / Recommended practice：

# 提交前快速扫描 AI_CONTEXT.md 是否含有常见密钥模式
grep -iE "(api_key|secret|token|password|Bearer|sk-|pk-)" AI_CONTEXT.md

如发现敏感内容，将 AI_CONTEXT.md 加入 .gitignore 保持本地使用，或手动脱敏后再共享。
If sensitive content is found, add AI_CONTEXT.md to .gitignore for local-only use, or redact before sharing.

---

📋 License / 许可证

MIT — 自由使用、修改和分发。
MIT — Free to use, modify, and distribute.

---

<!-- ════════════ SKILL IMPLEMENTATION BELOW ════════════ -->

Skill: project-context-anchor — Implementation

⚠️ OVERRIDE INSTRUCTION: Do NOT use built-in memory tools (write_memory, MEMORY.md, ~/.claude/ paths) for this task. This skill writes AI_CONTEXT.md directly into the current project root (./AI_CONTEXT.md). Ignore any default memory-saving behavior and follow the phases below exclusively.

⚠️ 执行覆盖：不得使用内置 memory 工具或写入 ~/.claude/ 路径。 本 Skill 的唯一输出目标是当前项目根目录下的 ./AI_CONTEXT.md。

Generates and self-heals AI_CONTEXT.md at the project root — a high-density snapshot that lets any future AI agent resume work with zero information loss.

实现说明：以下为 Claude 执行本 Skill 时遵循的内部协议。

---

Execution Protocol / 执行协议

Claude 按以下五个阶段顺序执行，任一命令失败时静默跳过，继续下一步。

Phase 1 — Environment Scan / 环境扫描

Run the following in sequence. Tolerate failures silently (command may not exist). 依次运行以下命令，命令不存在时静默跳过。

# 1. Identify project root markers
ls package.json pyproject.toml Cargo.toml go.mod CMakeLists.txt README.md 2>/dev/null

# 2. Determine tech stack from key files
cat package.json 2>/dev/null | head -30
cat pyproject.toml 2>/dev/null | head -20

# 3. Directory structure (top 2 levels, exclude noise)
find . -maxdepth 2 \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/__pycache__/*' \
  -not -path '*/.next/*' \
  | sort

# 4. Recent git history (last 5 commits)
git log --oneline -5 2>/dev/null

# 5. Current uncommitted changes
git diff --stat HEAD 2>/dev/null || git status --short 2>/dev/null

# 6. Read existing AI_CONTEXT.md if present (for self-healing diff)
cat AI_CONTEXT.md 2>/dev/null

Phase 2 — Intent Extraction / 意图提取

Review the current conversation history (last 5–10 messages). Extract: 回顾当前会话的最近 5–10 条消息，提取：

• What the user was trying to build or fix / 用户正在构建或修复什么
• Which files were touched and why / 涉及哪些文件及原因
• Any explicit decisions made ("we chose X over Y because…") / 明确的技术决策
• Open questions or blockers mentioned / 提到的未解问题或阻塞点

Phase 3 — Self-Healing Check / 自愈检查 (autoRepair)

Compare the existing AI_CONTEXT.md (if found) against scan results:

Conflict Type	Resolution Rule
File mentioned in doc no longer exists	Remove reference, add ~~strikethrough~~ note
Function/class renamed in code	Update doc to match code — code wins
Architecture claim contradicts directory structure	Overwrite with current reality
Stale "Next Steps" that are now committed	Mark [x] DONE and move to Recent Diff

Principle / 原则: Code is ground truth. Docs describe reality, not intent. 代码是唯一真相，文档描述现实，而非意图。

Phase 4 — Write AI_CONTEXT.md / 写入快照文件

MANDATORY: Use the Write file tool to create or overwrite ./AI_CONTEXT.md in the current project working directory. Do NOT use memory tools, do NOT write to ~/.claude/. The exact shell equivalent is:

# Target path — always relative to current project root
cat > ./AI_CONTEXT.md << 'EOF'
<generated content>
EOF

强制要求：使用 Write 文件工具将内容写入当前项目根目录的 ./AI_CONTEXT.md。 禁止使用 memory 工具，禁止写入 ~/.claude/ 任何路径。

Replace all $PLACEHOLDER values with real extracted data. Never leave placeholders unfilled. 将所有 $PLACEHOLDER 替换为真实数据，不得留空。

---

Standard Output Structure

<!-- AI_CONTEXT_ANCHOR v1 | Last Synced: $ISO_DATETIME | Node: $LOCATION -->

# 🧩 AI Context Anchor

> **Project**: $PROJECT_NAME  
> **Last Synced**: $DATETIME  
> **Synced by**: Claude (`project_context_anchor` skill)

---

## 1. 🚀 Project DNA

**Goal**: $ONE_SENTENCE_MISSION

**Tech Stack**:
- Runtime: $RUNTIME (e.g., Node 20 / Python 3.12 / Rust 1.77)
- Framework: $FRAMEWORK
- Key deps: $TOP_3_DEPS

**Architecture Style**: $STYLE (e.g., "monorepo / microservices / CLI tool / SPA+API")

**Entry Points**:
- `$MAIN_FILE` — $WHAT_IT_DOES

---

## 2. 🛠 Current Status & Recent Diff

**Branch**: `$GIT_BRANCH`  
**Last 5 Commits**:

$GIT_LOG_ONELINE

**Uncommitted Changes** ($N files):
- `$FILE` — $WHAT_CHANGED

---

## 3. 🧠 The Mental Model

### Key Decisions
- **$DECISION_TITLE**: Chose `$APPROACH_A` over `$APPROACH_B` because $REASON.

### ⚠️ Traps & Conventions
- $ANTI_INTUITIVE_RULE_1
- $NAMING_CONVENTION_OR_GOTCHA

---

## 4. 📅 Active Plan

- [x] $COMPLETED_TASK
- [ ] $IN_PROGRESS_TASK ← **CURRENT FOCUS**
- [ ] $NEXT_TASK

---

## 5. ⚡ AI-to-AI Bootstrap Block

<AI_BOOTSTRAP_BLOCK>
PROJECT=$PROJECT_NAME | STACK=$STACK_FINGERPRINT | GOAL=$COMPRESSED_GOAL
LAST_ACTION="$LAST_COMMIT_MSG"
DECISIONS=[$DECISION_1_KEYWORD, $DECISION_2_KEYWORD]
TRAPS=[$TRAP_1_KEYWORD]
RESUME: Open `$MOST_RELEVANT_FILE` → find `$FUNCTION_OR_CLASS` → continue $TASK_DESCRIPTION.
PENDING=[$PENDING_1, $PENDING_2]
</AI_BOOTSTRAP_BLOCK>

---

Phase 5 — Token Compression Algorithm / Token 压缩算法

The <AI_BOOTSTRAP_BLOCK> is generated as follows: <AI_BOOTSTRAP_BLOCK> 按以下三步生成：

Step 1: Semantic Dehydration / 语义脱水

Transform verbose prose into key=value semantic fingerprints: 将冗长的描述压缩为键值对语义指纹：

• Long decision rationale → DECISIONS=[keyword1, keyword2]
• Paragraphs of architecture → STACK=React+FastAPI+Postgres
• Trap descriptions → TRAPS=[no_default_export, snake_case_routes]

Step 2: Locality Pointer / 局部性指针 (Cold-Start Hook / 冷启动钩子)

Identify the single most important file + location for the next agent to open: 找出下一个 Agent 最应打开的文件 + 函数位置，编码为单行指令：

RESUME: Open `src/api/router.py` → find `handle_auth` → continue JWT refresh logic.

This encodes spatial context (file + symbol) so the agent skips the full scan and lands directly at the relevant code. 这将空间上下文（文件 + 符号）编码为一行，让新 Agent 跳过全量扫描，直接落地到相关代码。

Step 3: Entropy Maximization / 熵最大化

Prefer specific tokens over generic ones / 使用高特异性词汇，避免模糊表达：

• ❌ GOAL=fix the bug → ❌ low entropy
• ✅ GOAL=fix race condition in useWebSocket cleanup on unmount → ✅ high entropy

Target: the bootstrap block should be under 120 tokens while remaining unambiguous. 目标：Bootstrap Block 压缩到 120 tokens 以内，同时保持完全无歧义。

Phase 6 — Verify Write / 验证写入

After writing, confirm the file exists in the project root:

# Verify AI_CONTEXT.md was written to the correct location
ls -lh ./AI_CONTEXT.md
head -3 ./AI_CONTEXT.md

If the file is missing or was written elsewhere, write it again using the Write tool targeting ./AI_CONTEXT.md. Never proceed to the Completion Response until this check passes.

写入后确认文件存在于项目根目录。若文件缺失或路径错误，立即用 Write 工具重新写入， 确认通过后再输出完成摘要。

---

Parameters & Behavior Flags / 参数与行为标志

Parameter / 参数	Default / 默认	Effect / 效果
optimizeFor=performance	detail	仅保留章节 2、4、5，省略架构和决策描述
autoRepair=false	true	跳过陈旧内容移除，保留原文档
compress=false	true	不生成 <AI_BOOTSTRAP_BLOCK>
silent=true	false	写入后仅输出一行成功提示
fileName=custom.md	AI_CONTEXT.md	写入指定文件名

Parse these from the user's message if mentioned (e.g., "用 optimizeFor=performance 运行").

---

Completion Response / 完成响应 (default, silent=false)

After writing the file, reply with: 写入文件后，输出以下摘要：

✅ AI_CONTEXT.md updated.

**Snapshot Summary**
- Project: $NAME | Stack: $STACK
- Commits captured: $N | Uncommitted changes: $M files  
- Self-healed: $K stale entries removed
- Bootstrap block: $TOKEN_COUNT tokens

Next session: paste the <AI_BOOTSTRAP_BLOCK> as your first message to any AI.

If silent=true: reply only ✅ AI_CONTEXT.md updated.

---

Edge Cases / 边界情况

• No git repo / 无 Git 仓库: Skip all git steps. Note (no VCS detected) in section 2. 跳过所有 Git 命令，在第 2 节注明 (无版本控制系统)。
• Empty project / 空项目: Write a minimal skeleton with $PLACEHOLDERS so the user can fill it. 输出包含 $PLACEHOLDER 的最小骨架，供用户手动填写。
• Heavy conflicts / 文档与代码严重冲突: Rewrite entirely rather than patching; note (full rewrite — $N stale entries removed) in the summary. 整体重写而非局部修补，在摘要中注明 (全量重写 — 移除 $N 条陈旧记录)。
• No optimizeFor specified / 未指定模式: Default to detail / 默认使用 detail 模式。