Cs Learn
After a feature or fix, capture pitfalls and reusable knowledge into dated learning markdown under .codestable/compound/.
Overview
cs-learn is an agent skill most often used in Build PM (also Operate iterate after fixes) that archives pitfalls and best practices into Codestable learning markdown.
Install
npx skills add https://github.com/liuzhengdongfortest/codestable --skill cs-learnWhat is this skill?
- Two tracks: pitfall (problem/root cause/fix) and knowledge (default better practices)
- Writes .codestable/compound/ with doc_type learning and YYYY-MM-DD-learning-{slug}.md naming
- Phase 1.5 overlap search and update-existing path per shared-conventions before creating duplicates
- Triggered from cs-feat-accept and cs-issue-fix prompts or user phrases like 沉淀知识 / learning
- Startup requires .codestable/attention.md or directs to cs-onboard for skeleton completeness
- Two documentation tracks: pitfall and knowledge
- Mandatory Phase 1.5 overlap and update-existing check per shared-conventions
Adoption & trust: 959 installs on skills.sh; 902 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your specs document tasks but not the traps and better defaults the team paid for in blood during the last feature or bugfix.
Who is it for?
Teams using the Codestable skeleton who want lightweight institutional memory without a separate wiki.
Skip if: Repos without .codestable/attention.md and onboarding, or builders who only need one-off chat summaries with no persisted compound library.
When should I use this skill?
User says 沉淀知识, learning, or wants to record experience; or acceptance/fix workflows ask to save learnings; or after a hard-won debug outside normal flows.
What do I get? / Deliverables
You get a dated learning file in compound/ with pitfall or knowledge structure, linked context, and deduped updates when similar docs already exist.
- YYYY-MM-DD-learning-{slug}.md with doc_type learning in .codestable/compound/
- Updated existing learning doc when overlap path is chosen
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build PM because learnings close out delivery work and compound team memory alongside specs. Outputs are structured learning docs linked to feature/issue artifacts—project knowledge management, not runtime code.
Where it fits
After cs-feat-accept, capture API versioning pitfall linked to the feature spec directory.
After cs-issue-fix on prod config drift, document root cause and guard command as a pitfall learning.
Promote a repeated test harness pattern into a knowledge-track default for future features.
How it compares
Use as the post-delivery compound step in Codestable—not a generic note-taking skill outside the feature/issue workflow.
Common Questions / FAQ
Who is cs-learn for?
Solo and small teams on Codestable who finish features or issues and want pitfall and knowledge docs the agent can retrieve later.
When should I use cs-learn?
After cs-feat-accept or cs-issue-fix when prompted; when you say 沉淀知识 or learning; or after solving a costly one-off engineering problem worth recording.
Is cs-learn safe to install?
It writes markdown under your repo only; review the Security Audits panel on this Prism page and confirm compound paths match your conventions.
SKILL.md
READMESKILL.md - Cs Learn
# cs-learn ## 启动必读 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 每次做 feature 或修 issue 都会留下 spec 文件。但 spec 记录的是"做了什么"和"怎么做的"，**不会记录"踩了什么坑"和"发现了什么更好的做法"**。没有沉淀的团队总在重复解决同一个问题。 两条轨道： - **坑点轨道**（pitfall）：记录问题 / 根因 / 解法，防止下次再掉进同一个坑 - **知识轨道**（knowledge）：记录最佳实践 / 工作流改进 / 可复用模式 两者都写入 `.codestable/compound/`（共享目录见 `shared-conventions.md` 第 1 节"归档类文档"）。本技能产出 frontmatter 带 `doc_type: learning`，命名 `YYYY-MM-DD-learning-{slug}.md`。 --- ## 什么时候触发 | 情境 | 说明 | |---|---| | 完成 feature 工作流 | `cs-feat-accept` 主动问"要记录这次的学习点吗？" | | 完成 issue 工作流 | `cs-issue-fix` 主动问"要把这个坑记录下来吗？" | | 用户主动 | "记录一下"、"沉淀知识"、"learning"等 | | 解决了一次性难题 | 不在 feature / issue 内但花了大量时间才解决的工程问题 | 主动推荐一句话即可，用户说"不用了"立刻跳过——重复推可能让用户觉得 AI 在加戏。 --- ## 两条轨道各写什么 **坑点**：调试过的 bug / 绕过的配置陷阱 / 环境问题 / 集成失败……一切"本来应该好但没好"的经历。 **知识**：发现的最佳实践 / 工作流改进 / 架构洞见 / 可复用设计模式……一切"以后应该默认这样做"的学习。 frontmatter / 正文模板 / 完整示例见同目录 `reference.md`。 --- ## 工作流阶段 ### Phase 1：识别来源（自动） 从对话上下文提取： - **来源类型**：feature 工作流 / issue 工作流 / 独立问题 - **关联产物**：feature 目录 / issue 目录路径（如有） - **粗分轨道**：坑点 or 知识。"修了什么坏了的东西" = 坑点；"发现了什么更好做法" = 知识。两者都有就分两条 来源不明确问用户**一个问题**澄清不要猜。 ### Phase 1.5：查重叠与意图分流（必做） 按 `shared-conventions.md` §6 第 5/6 条： - 含"改 / 更新 / 补充 / 某条 learning"或指向某份旧文档 → 直接走**更新已有** - 否则用搜索工具按 `--filter tags~=` 或 `--query` 查一遍，命中相近旧文档时把候选列给用户 **更新路径**：读旧文档 → 和用户对齐要改哪几节（常见是补新踩的坑、补当时"没找到原因"的根因）→ 起草 diff → 写回原文件 + `updated: YYYY-MM-DD`，不新建。 ### Phase 2：提炼要点（一次一个问题） **坑点轨道**问： 1. "你最开始观察到的现象是什么？" 2. "哪些解法试过但没用？"（鼓励写，失败的尝试是后人最宝贵的信息——知道哪条路不通能省下大量时间） 3. "最终怎么发现真正原因的？" 4. "下次可以更早发现吗？怎么发现？" **知识轨道**问： 1. "你发现的这个模式，在什么情境下最有价值？" 2. "不这样做会出什么问题？" 3. "有没有不适用的反例？" 用户对某问题说"没什么"或"跳过"就跳过——宁可少一节也不用空话填充。 ### Phase 3：起草 + 用户 review AI 一次性起草完整文档（YAML frontmatter + 所有正文节）。一次性展示给用户。 ### Phase 4：归档 - 新建：写入 `compound/YYYY-MM-DD-learning-{slug}.md`（日期取**归档当天**），frontmatter 带 `doc_type: learning` - 更新：写回 Phase 1.5 定位的原文件 + `updated: YYYY-MM-DD` - supersede：按 `shared-conventions.md` §6 第 5 条处理 ### Phase 5：可发现性检查 写完若发现一两行"每次 CodeStable 技能启动都该知道"的项目硬约束，提示用户用 `cs-note` 追加到 `.codestable/attention.md`。不要自作主张改 attention，也不要写外部 AI 入口。 --- ## 搜索工具 > 完整语法见 `.codestable/reference/tools.md`。 ```bash # 按轨道筛选坑点 python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=pitfall --filter severity=high # 按组件查相关学习点 python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter component~={组件名} # 归档后查重叠 python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter tags~={主要 tag} --json ``` --- ## 守护规则 > 归档类共享规则见 `shared-conventions.md` 第 6 节。本技能特有： 1. **不混入 spec**——learning 不放进 `features/` 或 `issues/`；spec 也不放进 `compound/` 2. **只认自己的 doc_type**——只读写 `doc_type: learning` # learning 参考模板 本文件提供 `cs-learn` 的两条轨道模板和示例。产出文档写入 `.codestable/compound/`，文件名 `YYYY-MM-DD-learning-{slug}.md`。 ## 1. 坑点轨道（pitfall） ### frontmatter ```yaml --- doc_type: learning track: pitfall date: YYYY-MM-DD slug: {英文描述，连字符分隔} component: {受影响模块/层} severity: low | medium | high tags: [] --- ``` ### 正文结构 1. 问题 2. 症状 3. 没用的做法 4. 解法 5. 为什么有效 6. 预防 ## 2. 知识轨道（knowledge） ### frontmatter ```yaml --- doc_type: learning track: knowledge date: YYYY-MM-DD slug: {英文描述，连字符分隔} component: {适用模块/领域} tags: [] --- ``` ### 正文结构 1. 背景 2. 指导原则 3. 为什么重要 4. 何时适用 5. 示例 ## 3. 示例 完整示例可按仓库需要逐步补充；当前技能正文只保留流程，不再内嵌长示例。