agentsclimarketplace

Repo insight skill

Skill sqliang/deep-insight-engines/engines/repo-insight/repo-insight-skill

A highly structured, polyglot AI engine collection for personal learning, deep reading, repository analysis, and automated engineering workflows.

Install
npx -y skills add sqliang/deep-insight-engines --skill repo-insight-skill

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

专门用于深度分析和解读本地或 GitHub 源代码仓库的 Agent Skill。在 Claude Code 中全自动运行，包含质量 Review、迭代优化闭环、并行处理和 subAgent 支持。当用户说"帮我分析这个 GitHub 仓库"或"分析当前目录的代码"时，使用此技能。

SKILL.md

21.8 KB, ~7.7k tokens by cl100k_base, as published. Nobody here has run it

Repo Insight

专门用于深度分析和解读本地或 GitHub 源代码仓库的 Agent Skill。在 Claude Code 中全自动运行，包含质量 Review、迭代优化闭环、并行处理和 subAgent 支持。

⚠️ 关键输出质量规范（必须遵守）

1. 禁止 HTML 实体转义

CRITICAL: 生成所有 Markdown 文件时，严禁进行任何 HTML 实体转义。

  • ❌ 错误：>、<、&
  • ✅ 正确：>、<、&

检查方法：在写入文件后，验证输出文件中不包含 &gt;、&lt;、&amp; 这些字符序列。

2. Markdown 代码块规范

所有目录树、ASCII 图、代码示例必须放在正确的 Markdown 代码块中：

# 目录树必须放在 text 代码块中

# Mermaid 图必须放在 mermaid 代码块中

# TypeScript 代码必须放在 typescript 代码块中

3. 目录树格式规范

目录树注释必须：

  • 与目录/文件名之间保留 至少 2 个空格
  • 使用统一的注释标签：【核心基建】、【业务模块】、【工具集】、【配置】、【⚠️ 待分析】、【废弃】
  • 整个目录树必须包裹在 ```text 代码块中

示例：

repo-name/
├── src/                    # 【核心基建】源代码主目录
│   ├── main.ts            # 【核心基建】CLI 入口启动文件
│   └── utils/             # 【工具集】通用工具函数
└── README.md               # 【配置】项目说明文档

技能触发场景

使用此技能当用户：

  • 说"帮我分析这个 GitHub 仓库：https://github.com/..."
  • 说"分析当前目录的代码"
  • 要求深度解读代码库架构和业务逻辑
  • 需要代码仓库的中文翻译和注释

工作目录结构

当使用 URL 模式时，代码库克隆到固定的 github-sources 目录：

~/github-sources/
└── repo-name/
    ├── reports/
    │   ├── 00-planning/
    │   │   └── analysis_plan.md      # 阶段零输出
    │   ├── 01-global-scan/
    │   │   ├── repo_overview.md      # 阶段一输出
    │   │   └── draft_tree.md          # 阶段一输出
    │   ├── 02-architecture/
    │   │   ├── architecture.md        # 阶段二输出
    │   │   └── final_tree.md          # 阶段二输出
    │   ├── 03-deep-dive/
    │   │   ├── task_queue.md          # 阶段三输出
    │   │   └── comments_draft.md      # 阶段三输出
    │   ├── 04-quality/
    │   │   ├── quality_review.md      # 阶段4.5输出
    │   │   └── iteration_log.md       # 阶段4.5输出（如迭代）
    │   ├── final_report.md            # 阶段四输出
    │   ├── execution_summary.md       # 阶段五输出
    │   └── QUICKSTART.md             # 阶段五输出
    ├── README-CN.md（如需要）
    └── [源代码文件（带中文注释）]

当使用当前目录模式时：

./
├── reports/
│   ├── 00-planning/
│   │   └── analysis_plan.md
│   ├── 01-global-scan/
│   │   ├── repo_overview.md
│   │   └── draft_tree.md
│   ├── 02-architecture/
│   │   ├── architecture.md
│   │   └── final_tree.md
│   ├── 03-deep-dive/
│   │   ├── task_queue.md
│   │   └── comments_draft.md
│   ├── 04-quality/
│   │   ├── quality_review.md
│   │   └── iteration_log.md
│   ├── final_report.md
│   ├── execution_summary.md
│   └── QUICKSTART.md
├── README-CN.md（如需要）
└── [源代码文件（带中文注释）]

核心工作流

阶段零：准备与任务规划（新增）

目标：在开始分析前，先规划整个任务，确定优先级和并行策略

输入：目标 GitHub 仓库地址 / 原始代码文件集合

处理步骤：

  1. 运行可选辅助脚本获取基础信息

    • 可选运行 scripts/file_counter.py 获取文件统计
    • 可选运行 scripts/complexity_scanner.py 获取复杂文件列表

  2. 快速扫描仓库规模

    • 读取 README.md、package.json、pyproject.toml 等核心配置
    • 使用 Glob 工具快速浏览目录结构

  3. 制定分析计划

    • 评估仓库规模和复杂度
    • 确定哪些模块需要优先分析
    • 规划哪些任务可以并行执行
    • 预估时间和资源需求
    • 定义质量标准和验收条件（如"所有报告必须使用模板格式"）

  4. 创建任务清单

    • 生成 reports/00-planning/analysis_plan.md
    • 包含：任务列表、优先级、依赖关系、质量标准

输出：

  • reports/00-planning/analysis_plan.md - 分析计划文档

阶段一：全局扫描、输入与信息聚合、产品降维与文档基建

输入：

  • 目标 GitHub 仓库地址 / 原始代码文件集合
  • reports/00-planning/analysis_plan.md（如存在）

处理步骤：

  1. 物理层过滤干扰项

    • 排除第三方依赖包（node_modules/, vendor/, .git/, dist/, build/ 等）
    • 排除构建产物和环境配置文件
    • 使用 Glob 工具获取有效文件清单

  2. 结构展平与草稿目录树生成

    • 提取全局文件清单，构建基础的"全局目录层级树"
    • 基于 README 描述或业界通用命名规范，对目录树进行"职责域初步推测标注"
    • 对无法推测的目录打上"待定" Tag
    • 参考 references/tree_tpl_guide.md 模板生成 reports/01-global-scan/draft_tree.md

  3. 产品视野的业务心智初始化与选型提取

    • 锁定线索：优先扫描 README.md、docs/ 目录、package.json 等全局信息
    • 语义提炼：分析该仓库的核心定位、解决的具体痛点、适用的业务场景，提取/推导典型的使用 Case
    • 选型反推与对比：初步提取其核心技术方案，分析选择该方案的背景与合理性，强推导"方案选型对比"
    • 参考 references/repo_overview_tpl_guide.md 模板生成 reports/01-global-scan/repo_overview.md

  4. 国际化基建 (Doc Translation)

    • 语言嗅探：检测 README 和 docs 等目录下的核心文档语言
    • 本地化生成：若非中文且无中文版本，触发翻译流，在同级目录生成如 README-CN.md 等对应中文文档，不覆盖原文件

输出：

  1. 含有新增中文翻译文档的增强版目标源码集合
  2. reports/01-global-scan/draft_tree.md - 全局目录树，包含注释草稿，标注职责推测（参考 references/tree_tpl_guide.md）
  3. reports/01-global-scan/repo_overview.md - 结构化文档，包含定位/问题/场景/Case/方案初探等（参考 references/repo_overview_tpl_guide.md）

阶段二：宏观视野、架构设计梳理与靶向拓扑

输入：

  1. 目标源码仓库集合 (增强版，带翻译文档)
  2. reports/01-global-scan/draft_tree.md (全局物理目录与职责推测草稿)
  3. reports/01-global-scan/repo_overview.md (产品与业务上下文解析文档)
  4. reports/00-planning/analysis_plan.md (如存在)

处理步骤：

  1. 靶向寻路与入口解析

    • 读取 reports/01-global-scan/draft_tree.md，提取并解析高价值入口文件（如 package.json、全局 main/index 文件）和打着"待定"标签的神秘目录
    • 重点分析源代码文件，定位系统的全局入口、核心路由分发点、主控中心
    • 结合 reports/01-global-scan/repo_overview.md 的业务场景，带着"业务目的"寻找核心节点

  2. 实体识别与拓扑推导

    • 顺藤摸瓜，扫描入口文件引用的核心模块，梳理模块间的 Import/Export 依赖链路
    • 运用领域驱动设计 (DDD) 视角，识别代码中的核心业务实体及其在模块间的流转引用

  3. 架构梳理逆向绘制

    • 结合技术栈、源代码分析、模块依赖与上下文文档，逆向推导整体架构设计与核心模块设计
    • 将系统整体架构、路由调用关系、实体依赖、核心模块设计(3~5个)等转化为人类易读的 plainText (ASCII 字符画) 图表及详尽的文字说明

  4. 核心数据流转时序提取 (Data Flow Tracing)

    • 追踪核心场景下的数据是如何从入口输入，经过哪些模块/中间件/拦截器/服务等处理，最终落盘或返回的
    • 提取数据流各节点的交互时序与条件分支
    • 转换为 Mermaid sequenceDiagram 格式

  5. 规范化契约提取 (Contract Specification)

    • 扫描对外暴露的 Controller/Router 或公共暴露的 API 函数
    • 将提取的参数、返回值、状态码转化为 OpenSpec/OpenAPI 规范标准，内部调用逻辑转化为标准 TypeScript Interface

  6. 实体树收敛

    • 根据源码实际验证结果，推测不同目录对应的业务职责（哪些是核心业务，哪些是通用工具）
    • 修正阶段一的目录职责推测，打平未知目录
    • 生成 reports/02-architecture/final_tree.md

  7. 生成架构文档

    • 参考 references/architecture_tpl_guide.md 模板生成 reports/02-architecture/architecture.md
    • 确保使用 plainText ASCII 字符画绘制结构图（严禁使用 Mermaid 或 Markdown List 代替）
    • 数据流部分必须且仅能使用 Mermaid 的 sequenceDiagram

输出：

  1. reports/02-architecture/architecture.md - 《架构与拓扑梳理文档》（参考 references/architecture_tpl_guide.md）
  2. reports/02-architecture/final_tree.md - 经源码验证的最终版目录树

阶段三：微观深度阅读与知识资产化（增强 subAgent 设计）

输入：

  1. 阶段一产物: reports/01-global-scan/repo_overview.md
  2. 阶段二的所有产物: reports/02-architecture/architecture.md、reports/02-architecture/final_tree.md
  3. 目标源码仓库集合 (增强版，带翻译文档)
  4. reports/00-planning/analysis_plan.md (如存在)

处理步骤：

  1. 分块调度与任务分配

    • 基于 reports/02-architecture/final_tree.md 和 complexity_scanner.py 输出
    • 将高复杂度模块分成独立任务
    • 每个任务包含：文件路径、优先级、预估复杂度、验收标准
    • 生成 reports/03-deep-dive/task_queue.md

  2. 并行子Agent处理

    • 可并行的任务类型：
      • 不同核心模块的深度阅读
      • 不同业务实体的注释生成
      • 不同功能模块的业务逻辑分析
    • 子Agent任务格式： 
      深度阅读任务：
- 文件路径：src/core/engine.py
- 优先级：高
- 上下文：repo_overview.md + architecture.md
- 验收标准：[具体质量要求]
- 输出：comments_draft.engine.md
    • 合并策略：
      • 所有子Agent完成后，合并 comments_draft.*.md 到 comments_draft.md
      • 进行一致性检查

  3. 主 Agent 协调

    • 监控任务进度
    • 处理子Agent之间的依赖
    • 质量把关最终合并结果

  4. 靶向阅读（如果不使用 subAgent）

    • 从核心入口开始逐级阅读
    • 重点阅读核心业务逻辑、复杂算法、关键设计模式实现

  5. 逻辑反推与业务对齐

    • 阅读源码时，不仅解释技术逻辑，还要与阶段一中的 reports/01-global-scan/repo_overview.md "业务场景"对齐
    • 推导其"解决什么问题"以及"为什么这么写"
    • 例如添加注释：这里的容错处理是为了应对阶段一提到的高并发场景 Case

  6. 知识资产化

    • 在内部工作区按照目标语言的业界标准，生成针对文件、核心类、复杂函数、难理解的核心逻辑的带规范的拟注入注释草案
    • 生成 reports/03-deep-dive/comments_draft.md，包含目标文件路径、目前代码内容的注释范围、注释规范与原则等内容

输出：

  • reports/03-deep-dive/task_queue.md - 任务队列（如使用 subAgent）
  • reports/03-deep-dive/comments_draft.md - 全量代码注释内容库草案

阶段四：产物组装与实体注入

输入：

  • 阶段一的 reports/01-global-scan/repo_overview.md
  • 阶段二的 reports/02-architecture/architecture.md 和 reports/02-architecture/final_tree.md
  • 阶段三的注释草案
  • 增强版源码
  • reports/00-planning/analysis_plan.md (如存在)

处理步骤：

  1. 报告整合

    • 将阶段一、阶段二、阶段三的所有核心内容无缝融合成最终的《全方位深度解读报告》
    • 必须包含 repo_overview.md 的完整内容（项目概览、技术亮点等）
    • 必须包含 architecture.md 的完整内容（所有架构图、模块设计、数据流时序图、接口契约等）
    • 必须包含 comments_draft.md 的注释规范
    • 生成 reports/final_report.md，结构参考 references/final_report_tpl_guide.md
    • **CRITICAL: 不要只保留高层概述，要保留所有技术细节和图表

  2. 物理注释融合

    • 将注释精准写入代码文件
    • 创建备份或使用 git 进行版本控制（如果适用）

  3. 完整性自检

    • 校验生成的文档是否覆盖了所有需求点
    • 检查注入的注释是否符合预设的注释规范

输出：

  1. reports/final_report.md - 《全方位深度解读报告》(业务价值篇 & 架构设计篇)
  2. 注入了详尽规范注释的"全新代码库"

阶段4.2：输出质量检查（新增）

目标：在进行质量 Review 之前，先进行格式和完整性检查，确保输出符合规范。

检查清单：

  1. HTML 转义检查

    • 检查所有 Markdown 文件中无 &gt;、&lt;、&amp;
    • 确认 >、<、& 都原样保留

  2. 目录树格式检查

    • 检查 draft_tree.md 在 ```text 代码块中
    • 检查 final_tree.md 在 ```text 代码块中
    • 检查目录树注释与目录名之间有足够空格
    • 检查注释标签格式统一（【核心基建】、【业务模块】等）

  3. 最终报告完整性检查

    • 检查 final_report.md 包含 repo_overview.md 的所有核心内容
    • 检查 final_report.md 包含 architecture.md 的所有 ASCII 架构图
    • 检查 final_report.md 包含 architecture.md 的所有 Mermaid 时序图
    • 检查 final_report.md 包含 architecture.md 的所有接口契约定义
    • 检查 final_report.md 有清晰的章节结构和导航

  4. 图表规范检查

    • 检查所有 ASCII 图使用统一字符集（+、-、|、>、v、^）
    • 检查所有 Mermaid 图语法正确且可渲染
    • 检查架构图层次清晰，箭头方向一致

输出：

  • 如果检查全部通过：继续阶段 4.5
  • 如果发现问题：先修正问题，再继续

阶段4.5：质量 Review 与反思 + 迭代优化（新增）

目标：形成完整的质量检查 → 问题发现 → 计划改良 → 问题解决 → 再次检查的闭环

输入：

  • 阶段零到阶段四的所有输出文件
  • reports/00-planning/analysis_plan.md

处理步骤：

第一部分：质量 Review

  1. 完整性检查

    • 检查所有应生成的文件是否存在（对照 analysis_plan.md）
    • 检查报告格式是否符合模板要求
    • 检查关键内容是否缺失（对照 analysis_plan.md 的验收标准）

  2. 一致性检查

    • repo_overview.md 与 architecture.md 的业务描述是否一致
    • draft_tree.md 与 final_tree.md 的演变是否合理
    • 注释与业务场景是否对齐
    • 各子模块的注释风格是否统一

  3. 质量反思

    • 架构图是否清晰易读
    • 注释是否准确有用
    • 报告是否有遗漏的重要模块
    • 生成 reports/04-quality/quality_review.md，包含：
      • 问题清单（严重程度：高/中/低）
      • 根本原因分析
      • 改进建议

第二部分：迭代决策与执行

  1. 问题评估与优先级排序

    • 评估每个问题的影响范围和严重程度
    • 确定哪些问题必须解决，哪些可以延后
    • 更新 reports/00-planning/analysis_plan.md（添加迭代任务）

  2. 决定迭代策略

    • 轻量级修正（问题较少且局部）：
      • 直接修改相关报告文件
      • 跳过完整阶段重跑
    • 部分阶段重跑（问题影响某个阶段）：
      • 确定需要重跑的阶段（如阶段二、阶段三）
      • 更新该阶段的输入
      • 重新执行该阶段
    • 完整迭代（问题严重且广泛）：
      • 回到阶段零，重新制定分析计划
      • 完整执行所有阶段

  3. 执行修正与优化

    • 按照迭代策略执行修正
    • 记录所有修改内容到 reports/04-quality/iteration_log.md

  4. 再次 Review（递归）

    • 修正完成后，回到"质量 Review"步骤
    • 检查问题是否解决
    • 是否引入新问题
    • 直到满足质量标准或达到最大迭代次数（默认最多2-3次）

迭代终止条件：

  • ✅ 所有严重问题已解决
  • ✅ 中等问题已解决或达成共识
  • ✅ 达到质量标准
  • ⚠️ 或达到最大迭代次数（避免无限循环）

输出：

  • reports/04-quality/quality_review.md - 质量审查报告
  • reports/00-planning/analysis_plan.md - 更新后的分析计划（包含迭代任务）
  • reports/04-quality/iteration_log.md - 迭代日志（记录所有修改）
  • 优化后的各报告文件

阶段五：交付与总结（增强）

输入：

  • 阶段零到阶段4.5的所有输出文件
  • 全新代码库（带注释）

处理步骤：

  1. 生成最终总结

    • 整合所有阶段的输出
    • 生成 reports/execution_summary.md
    • 包含：
      • 时间统计（各阶段耗时）
      • 迭代次数和修改记录
      • 文件清单
      • 关键发现
      • 未解决的问题（如有）
      • 未来优化建议

  2. 生成快速预览

    • 创建 reports/QUICKSTART.md
    • 帮助用户快速浏览分析结果
    • 包含：仓库概览、核心架构、关键文件列表

  3. 交付展示

    • 生成文件树展示所有输出
    • 提供使用建议
    • 说明如何阅读各报告

输出：

  • reports/execution_summary.md - 执行总结
  • reports/QUICKSTART.md - 快速浏览指南
  • reports/04-quality/iteration_log.md - 迭代日志（如进行了迭代）

并行处理策略

可并行的环节

阶段一内并行：

  • 读取 README.md 和 package.json 等配置文件（并行读取）
  • 目录树生成 + 技术栈初步识别（可并行）

阶段二内并行：

  • 架构梳理 + 实体识别（部分可并行）
  • 数据流分析 + 接口契约提取（可并行）

阶段三完全并行：

  • 多个高复杂度模块的深度阅读（完全并行）

阶段4.5内并行（如有多个独立问题）：

  • 不同模块的问题修正（可并行）

不可并行（有依赖）的环节

  • 阶段零 → 阶段一 → 阶段二 → 阶段三 → 阶段四 必须顺序执行
  • Review 环节必须在阶段四之后
  • 迭代修正后必须再次 Review

执行指南

开始分析

当用户请求分析仓库时：

  1. 确定分析模式

    • 如果用户提供了 GitHub URL → URL 模式
    • 如果用户说"分析当前目录" → 当前目录模式

  2. URL 模式处理

    • 克隆仓库到 ~/github-sources/ 目录
    • 切换到仓库目录

  3. 当前目录模式处理

    • 确认当前目录是 git 仓库或代码目录
    • 在当前目录下工作

  4. 创建 reports 目录

    • mkdir -p reports

  5. 按顺序执行所有阶段（从零开始）

关键工具使用

  • Glob: 用于文件搜索和目录扫描
  • Read: 用于读取代码文件和文档
  • Grep: 用于代码搜索和模式匹配
  • Write: 用于生成报告文件
  • Edit: 用于注入代码注释
  • Bash: 用于 git 操作和目录管理
  • Agent: 用于并行处理子任务（阶段三）

可选辅助脚本

技能包含以下可选的 Python 辅助脚本（在 scripts/ 目录下），可用于快速获取统计信息：

  • scripts/file_counter.py - 统计文件数量和代码行数

    • 用法: python3 scripts/file_counter.py <仓库路径>
    • 输出: JSON 格式的统计信息

  • scripts/complexity_scanner.py - 找出 TOP 10 最复杂文件（基于行数）

    • 用法: python3 scripts/complexity_scanner.py <仓库路径>
    • 输出: JSON 格式的复杂文件列表

这些脚本是可选工具，可以根据需要使用，输出结果可作为分析参考。

注意事项

  1. 全自动执行 - 调用后无需中间交互，直接完成所有分析工作
  2. 保持原有代码 - 注释注入时不要破坏原有代码结构
  3. 不覆盖原文件 - 翻译文档时生成新文件（如 README-CN.md）
  4. 使用 ASCII 图表 - 架构图必须使用 plainText ASCII 字符画
  5. 参考模板文件 - 始终使用 references/ 目录下的模板作为输出格式参考
  6. 质量优先 - Review 环节发现问题后，按照迭代策略进行优化
  7. 避免无限循环 - 最多迭代 2-3 次，或达到质量标准即可停止

参考模板

技能包含以下参考模板文件（在 references/ 目录下）：

  • repo_overview_tpl_guide.md - 产品与业务上下文解析报告模板
  • architecture_tpl_guide.md - 架构与拓扑梳理文档模板（含图表绘制规范）
  • tree_tpl_guide.md - 目录树模板（含格式规范）
  • final_report_tpl_guide.md - 最终报告整合模板（新增）

在生成对应报告时，请务必参考这些模板的格式和内容要求。特别是 final_report.md 必须严格按照 final_report_tpl_guide.md 的结构来整合所有阶段的内容。

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.