Cursor Skill Infra (Reference Library)

一套可复制的 Cursor hooks + Rules + skill-rules 参考实现，用来解决：

• Skills 不会自动激活（需要你自己记得用）
• 激活过程不可观测（你不知道为什么命中/没命中）
• 规则/技能散落（难以维护、难以迁移）

本仓库不是应用程序，而是 基础设施模板：把你需要的文件复制到你自己的项目即可。

设计来源与差异点（你最该先读的 3 句话）

• 参考了原版 repo 的思路：用 skill-rules.json 做路由，用 hook 在每次提交 prompt 前生成“技能建议/提示词注入”信号（原版多用 stdout 注入）。
• 做了 Cursor 环境适配：Cursor 更适合“落盘可审计”——建议写到 .cursor/context/skill-suggestions.md，再用 .cursor/rules/*.mdc 强制消费（而不是只靠 stdout）。
• 可与 zettelkasten-agent-skills 搭配：这个 repo 提供“基础设施（自动激活/可观测）”，zettelkasten-agent-skills 提供“技能库（SKILL.md + resources）”。

Attribution（致敬原项目）

• 本项目的路由/自动激活设计参考了 Claude Code Infrastructure Showcase 的 hooks + skill-rules.json 思路。
• Skills 的结构化写法参考了 Anthropic 的 skills 最佳实践（例如 skill-creator）：https://github.com/anthropics/skills/tree/main/skills/skill-creator

你会得到什么

• 自动建议 skills：每次提交 prompt 时，hook 会基于 prompt + 最近文件上下文给出建议
• 落盘可审计：建议写入 .cursor/context/skill-suggestions.md，调试写入 .cursor/hook-debug/last.json
• Rules 强制消费：用 .cursor/rules/*.mdc 让“先读建议再行动”成为默认行为（而不是靠记忆）

快速开始（5 分钟）

1. 把本仓库的 cursor/ 目录复制到你的项目根目录，并重命名为 .cursor/
2. 确认 .cursor/hooks.json 存在（Cursor 会在对应事件触发 hooks）
3. 修改 .cursor/skill-rules.json 的 pathPatterns/keywords/intentPatterns 以适配你的项目
4. 在 Cursor Chat 输入一句会命中的 prompt（例如“帮我写周报”或“整理这篇文献笔记”）
5. 打开 .cursor/context/skill-suggestions.md 查看命中结果

搭配 zettelkasten-agent-skills（推荐用法）

如果你已经有 zettelkasten-agent-skills（一套可直接复制的 skills 目录）：

1. 先把本仓库的 cursor/ 复制到你的项目并改名为 .cursor/
2. 再把 zettelkasten-agent-skills/skills/ 复制到你的项目 .cursor/skills/
3. 根据你的目录结构，调整 .cursor/skill-rules.json 的 pathPatterns

本仓库也内置了一个示例 weekly-report skill（见 skills/weekly-report/），你可以直接复制到 .cursor/skills/ 使用。

目录结构

cursor/                 # 复制到你的项目后改名为 .cursor/
  hooks.json
  hooks/
    skill-activation.js
    context-tracker.js
  rules/
    auto-activation.mdc
    core-entry.mdc
    single-source-of-truth.mdc
  skill-rules.json

skills/                 # 示例 skills（可选）
examples/               # 示例与截图（可选）

重要安全提醒（不要提交到 Git）

• .cursor/context/（包含工作区路径、最近文件等）
• .cursor/hook-debug/（可能包含 prompt、transcript_path 等敏感信息）

文档

• 集成指南：INTEGRATION_GUIDE.md
• 排障手册：TROUBLESHOOTING.md
• 架构与原理（泛化版）：docs/architecture.md

---

English (Short)

What is this?

This is a reference template for Cursor projects that want auto-activating skills:

• Hook-based matching via skill-rules.json (keywords / intent patterns / file context)
• Auditable outputs written to .cursor/context/ (instead of relying on transient stdout logs)
• .cursor/rules/*.mdc to enforce “read suggestions before acting”

Credits

• Inspired by Claude Code Infrastructure Showcase: https://github.com/diet103/claude-code-infrastructure-showcase
• Skill authoring best practices inspired by Anthropic skills: https://github.com/anthropics/skills/tree/main/skills/skill-creator