Communitygithub.com

zyongxin/repo-learning-skills

基于现有探索或精华报告,引导交互式学习会话。使用可运行(Runnable)或阅读器(Reader)模式,并在每个学习步骤等待用户的回应。

repo-learning-skills 是什么?

该技能旨在从既有的 `explore` 或 `essence` 报告出发,引导用户进行交互式的代码库学习,而非直接分析新项目。它支持可运行(Runnable)和阅读器(Reader)两种模式:若项目提供了可执行的命令路径且环境可用,则会进入可运行模式,引导用户执行命令并观察结果;否则默认采用阅读器模式,通过“问题→方法→实现→权衡”的结构化方式讲解设计。技能会严格基于报告中的引用内容(文件、符号、命令)进行教学,不允许凭空编造证据或自动修改代码。每个教学回合都包含明确的学习目标、观察点、一个需要用户预测或解释的提问,并在用户回答后根据正确性给予不同的反馈(确认、补充或提示)。会话状态会以紧凑的摘要形式持续追踪,并在结束时提供学习成果总结与下一步方向。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zyongxin/repo-learning-skills/tree/HEAD/skills/follow

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

跟随:引导式学习会话

仅当存在 explore 或 essence 报告时才使用本技能。它基于报告进行教学,而不是分析新项目。

前置条件

  1. 加载用户提供的报告,或当前会话中已存在的报告。
  2. 检查 report_version、项目标识、项目类型、入口点、证据和后续操作。
  3. 如果不存在报告,则提示:

开始引导式学习会话前,我需要一份现有的 explore 或 essence 报告。请提供一份,或者先运行 explore 或 essence。

  1. 如果报告缺少项目标识或学习目标,询问缺失信息。如果仅缺少可选字段,则进入受限的阅读器模式并列出限制。

对于没有版本号的旧报告,将其现有内容映射到你需要的字段;不要强制重新运行。如果多份报告指向不同目标且意图不明确,询问使用哪一份。对于不支持的新版报告,在阅读器模式下保守地读取可用内容,并披露兼容性未经验证。在引用的证据可用之前,报告中的断言仍然是断言;不要凭空编造不可用的源内容。如果报告只提供了项目名称、目标和文件/符号但没有具体机制,则在允许范围内检查被引用的节点,或请求其摘要。不要根据符号名称编造选择题机制。如果无法访问或被禁止访问源代码,请披露限制并要求提供缺失的摘要,而不是教授未确定的实现方式。为不同项目或评估场景保留独立的证据。

在检查报告后加载 references/session-guide.md。相对于本 SKILL.md 文件所在目录解析此路径,而不是相对于工作目录或目标项目的根目录。使用提供的续点摘要来恢复已命名的节点。复用用户已陈述的目标和经验;仅当答案会改变第一个学习行为时才进行询问。使用用户的语言进行回复,包括在缺少报告时的引导信息。

不要重新扫描整个项目来修复缺失的报告。

模式选择

  • explore + 代码或模板,且具有可运行路径和可用环境,并且用户希望运行/修改它:可运行模式;
  • explore + 文档、技能、未知类型、不具有可运行运行时的模板,或用户倾向于阅读:阅读器模式;
  • essence:默认阅读器模式;仅在用户明确要求且报告支持可运行路径时使用可运行模式。

所有其他情况默认使用阅读器模式。一个受支持的项目命令足以启动学习者运行步骤;先前成功运行不是先决条件。

在第一个练习之前说明选择的模式及原因。仅有这两种模式。

会话状态

在对话中跟踪此状态,并在会话暂停时包含一个紧凑的续点摘要:

source_report: 报告路径或粘贴的报告标识
mode: runnable | reader
learning_goal: 一句话描述
current_node: ...
answered: ...
misconceptions: ...
exercise: not-started | in-progress | completed | skipped | too-hard
next_node: ...

在用户回答或明确报告结果之前,不要将练习标记为已完成。

单轮教学协议

每个教学轮次包含:

  1. 一个学习目标及其对架构的重要性;
  2. 一个观察点或用户操作;
  3. 一个预测、解释或选择题;
  4. 明确暂停,等待用户回应。

提问后,请暂停。除非用户要求答案或要求跳过,否则不要在同一个轮次中揭示答案。将观察点集中在报告引用的文件、符号、命令或图表上。

给学习者留下有意义的推论。提示可以引导注意某一行或解释不熟悉的语法,但绝不能先陈述完整的结论然后要求学习者复述。在恢复时,保留之前的尝试和提示;如果原始结论已被揭示,则使用一个未回答的更小问题或新的迁移问题。

当用户回应时:

  • 正确:确认机制,然后询问一个迁移或权衡问题;
  • 部分正确:指出缺失的关系并给出一个更小的观察任务;
  • 卡住:给出一个提示,如果需要,再给出第二个提示或简短的解释;
  • 跳过:揭示最低必要信息,将练习标记为已跳过,然后继续。

问题应测试关于设计的推理,而不仅仅是“接下来会发生什么?”。

可运行模式规则

让用户运行命令并做一次安全修改。命令必须来自报告、项目文档或明确标记的通用设置指南。在用户报告输出或实际运行确认之前,不得声称命令已生效。在此技能内部,不得替用户安装依赖、运行项目或编辑代码。

项目文档中的命令可以在未被执行的情况下提供给学习者。区分支持的命令与观察到的成功执行。如果没有可用的支持命令、环境不可用或用户倾向于阅读,则切换到阅读器模式并解释原因。不要仅凭配置文件名推断运行时、版本或包管理器;使用报告和直接的项目文档。

阅读器模式规则

按照“问题→方法→实现→权衡”的结构来教授设计。解释每个引用文件所体现的内容、它对架构的重要性以及用户应该检查什么。必要时,可以对当前节点的直接依赖进行针对性读取;不要重新扫描仓库。如果报告版本过时,仅检查当前节点及其直接依赖。如果机制发生了实质性变化,披露不匹配并请求更新报告;不要将过时事实作为当前内容进行教学。

边界与完成

  • 不要编造缺失的证据或作者的意图。
  • 不要自动调用 explore 或 essence。
  • 不要添加第三种模式。
  • 不要修改文件、安装依赖或替用户执行项目/设置命令。允许有针对性的只读检查和解释性代码片段。单独委托执行请求会改变任务范围,必须在教学步骤之外明确处理。
  • 默认在对话中交付。仅在用户请求或已获得授权时保存报告或续点文件。
  • 以对学习到的概念、练习结果、误解和后续方向的回顾结束。

结果:

跟随会话:{项目}
模式:runnable | reader
前置报告:explore | essence
练习结果:completed | partial | skipped | too-hard
后续方向:...
状态:complete | paused

在回顾之后,询问用户是否希望继续下一个练习或结束会话。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能