repo-research

Repo Research

GitHub repository deep research tool, whose core goal is to draw inspiration fromexternal projects, and provide actionable improvement suggestions for the user's own project.

Scope of application: This skill applies to researching any type of GitHub repository, not limited to Claude Skills. It can be used to research open-source projects, libraries, frameworks, tools, etc.

Dependency Management

The core functionality of this skill (single/multiple repository research)does not requireany prerequisite skills.

Only when usingtopic-driven search modeare the following optional dependencies required:

Dependency skill	Purpose	Installation source	Requirement
find-skills	Search GitHub for related repositories by topic	`https://skills.sh/vercel-labs/skills/find-skills`	Optional

Usage Instructions：

If you directly provide a GitHub URL, this skill will directly use the existing single/multiple repository research mode
If you provide topic keywords (such as "research OCR-related projects"), this skill will:
1. First detect whether find-skills is installed
2. If not installed, it will prompt you to install it before continuing
3. After installation, automatically call find-skills to search

Configuration

This skill supports customizing the output directory and other settings through a configuration file.

Configuration File Location

skills/repo-research/assets/config.yaml

Quick Configuration

Copy the example configuration:

cp skills/repo-research/assets/config.example.yaml skills/repo-research/assets/config.yaml

Edit config.yaml, and set your output directory:

research:
  output_dir: "~/Documents/研究笔记"  # 支持绝对路径、相对路径、~ 展开

Configuration Item Description

Configuration item	Description	Default value
`research.output_dir`	Research report output directory	`./research`
`research.report_format`	Report format	`markdown`
`research.shallow_clone`	Use shallow clone	`true`
`security.enabled`	Enable security analysis	`true`
`security.prompt_analysis`	Prompt security detection	`true`

Configuration Reading Logic

1. 检查 skills/repo-research/assets/config.yaml 是否存在
2. 如果存在，读取配置
3. 如果 output_dir 为空或不存在，使用默认值 ./research
4. 支持路径展开：
   - `~` 展开为用户目录
   - 相对路径基于当前工作目录

Default Behavior (No Configuration File)

If there is no configuration file or output_dir is empty, the default behavior will be used:

Output directory：./research(the research folder under the current working directory)
Report format：Markdown
Security analysis: Enabled

Quick Start

# 单个仓库研究
/repo-research https://github.com/user/repo

# 多仓库对比研究
/repo-research https://github.com/user/repo-a https://github.com/user/repo-b

# 指定分析重点
/repo-research https://github.com/user/repo --focus=architecture

# 与现有技能整合
/repo-research https://github.com/user/repo --integrate-with=de-ai-polish

Trigger in conversation: Automatically activated when the user mentions phrases such as "research this repository", "compare and analyze these projects", "what inspiration does this give my project", etc.

Configuration

Configuration File

This skill supports customizing settings such as the output directory through a configuration file.

Configuration File Location

~/.openclaw/skills/repo-research/assets/config.yaml

Configuration Example

# 研究报告输出目录
# 支持绝对路径、相对路径和 ~ 展开
output_dir: "/Users/yourname/Desktop/Clawd/99 - 🦐 大虾研究/09 - 📋 研究报告"

# 报告格式：markdown 或 json
report_format: markdown

# 是否自动打开报告（生成后）
auto_open_report: false

# 克隆深度：1 = 浅克隆（更快），0 = 完整克隆
clone_depth: 1

Environment Variable Override

Configuration can also be set through environment variables (higher priority than the configuration file):

Environment variable	Description
`REPO_RESEARCH_OUTPUT_DIR`	Output directory
`REPO_RESEARCH_FORMAT`	Report Format
`REPO_RESEARCH_AUTO_OPEN`	Auto Open
`REPO_RESEARCH_CLONE_DEPTH`	Clone Depth

Output Directory Structure

output_dir/
└── research/
    └── YYYYMMDD-topic-slug/
        ├── repo-name/                    # 克隆的仓库
        ├── repo-name-2/                  # 多仓库时有多个
        └── topic-slug-report.md          # 研究报告（如：twitter-skills-report.md）

Workflow

Mode Selection

Automatically select the research mode based on the input:

Input Type	Research Mode	Output
Single GitHub URL	Single-repository Deep Research	Single-repository Analysis Report + Inspiration Suggestions
Multiple GitHub URLs	Multi-repository Comparative Research	Comparative Analysis Report + Common Inspiration
GitHub URL + Local Path	Comparative Inspiration Mode	Difference Analysis + Improvement Suggestions
Topic/Keywords	Topic-driven Search Research	Search Results + Multi-repository Comprehensive Analysis Report

Topic-driven Search Research Mode

Use this mode when the user provides topic keywords instead of a specific GitHub URL.

Trigger Conditions

Automatically activated when the user expresses the following needs:

"Help me find relevant projects about X"
"Search and research topic X"
"Find some open-source projects about X"
"What repositories about topic X are worth researching"

Workflow

Step 0: Dependency Check

# 检查 find-skills 是否已安装
if ! /find-skills --help >/dev/null 2>&1; then
    echo "⚠️  主题驱动搜索模式需要 find-skills 技能"
    echo "正在为您安装..."
    /skill-manager install https://skills.sh/vercel-labs/skills/find-skills
fi

Conversation Prompt：

"Detected that you need to use the topic search function. Checking dependencies..."

Step 1: Use find-skills to Search for Relevant Repositories

Call the find-skills skill to search:

/find-skills <主题关键词>

Example:

/find-skills pdf converter - Search for PDF conversion-related skills
/find-skills video transcription - Search for video transcription-related skills
/find-skills ocr - Search for OCR-related skills

Step 2: Organize Search Results

Extract from the return of find-skills:

Repository Name
GitHub URL
Brief Description
Relevance Score

Search Results Organization Format：

#	Repository Name	URL	Description	Relevance
1	[name]	[url]	[Description]	⭐⭐⭐⭐⭐
2	[name]	[url]	[Description]	⭐⭐⭐⭐☆

Step 3: User Confirmation and Filtering

Conversational Inquiry：

"Found [N] relevant repositories. Please select the projects to research in depth:" "1. Research all [N] repositories" "2. Select specific numbers (e.g., 1,3,5)" "3. Research only the top [K] most relevant" "4. Custom selection"

Determine the final research list based on the user's selection.

Step 4: Batch Cloning and Parallel Analysis

4.1 Create Research Directory

⚠️ Important: Prefer using the output_dirfrom the configuration file; if not configured, use the current working directory.

Python Method (Recommended)：

from scripts.config import get_research_dir

# 自动读取配置文件，返回研究目录路径
RESEARCH_DIR = get_research_dir(topic_slug)

Bash Method (Backward Compatible)：

# 优先使用配置文件中的 output_dir，否则使用当前目录
SKILL_DIR="$HOME/.openclaw/skills/repo-research"
CONFIG_FILE="$SKILL_DIR/assets/config.yaml"

# 尝试从配置文件读取 output_dir
if [ -f "$CONFIG_FILE" ] && command -v python3 &> /dev/null; then
    OUTPUT_DIR=$(python3 -c "
from pathlib import Path
import sys
sys.path.insert(0, '$SKILL_DIR/scripts')
from config import get_output_dir
print(get_output_dir())
" 2>/dev/null)
else
    OUTPUT_DIR="${PWD}"
fi

RESEARCH_DATE=$(date +%Y%m%d)
# 将主题转换为 slug 格式（小写、空格替换为连字符）
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

# 使用绝对路径确保在正确位置
RESEARCH_DIR="${OUTPUT_DIR}/research/${RESEARCH_DATE}-${TOPIC_SLUG}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"

4.2 Batch Cloning

for url in "${SELECTED_URLS[@]}"; do
    repo_name=$(basename "$url" .git)
    echo "正在克隆: $repo_name"
    git clone --depth 1 "$url" "$repo_name"
done

4.3 Parallel Analysis

Perform basic analysis on each cloned repository (see "Step 2: Basic Analysis").

Step 5: Generate Topic Comprehensive Report

Use assets/topic-research-template.md as the template.

Report Structure

# [主题] 综合研究报告

> **研究日期**：YYYY-MM-DD
> **搜索主题**：[主题关键词]
> **研究仓库数**：[N] 个
> **报告路径**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

## 执行摘要

### 研究概述

[用一段话概括：基于主题搜索了哪些类型的仓库，主要发现了什么]

### 一句话总结

[用一句话概括最关键的发现]

### 核心指标

| 指标 | 数值 |
|:-----|:-----|
| 搜索结果总数 | [N] 个仓库 |
| 深度研究数量 | [M] 个仓库 |
| 相关技术栈 | [列举主要技术] |
| 活跃项目占比 | [X%] |

---

## 搜索结果概览

### 仓库清单

| # | 仓库名 | 描述 | 语言 | Stars | 活跃度 |
|:-|:-------|:-----|:-----|:-----|:-------|
| 1 | [name] | [描述] | [lang] | [★] | 🟢 活跃 |
| 2 | [name] | [描述] | [lang] | [★] | 🟡 中等 |

### 分类汇总

**按技术类型**：
- [技术1]: [数量] 个项目
- [技术2]: [数量] 个项目

**按功能类型**：
- [功能1]: [数量] 个项目
- [功能2]: [数量] 个项目

---

## 技术栈分析

### 主流技术选择

| 技术 | 使用项目数 | 占比 | 代表项目 |
|:-----|-----------|:-----|:---------|
| [技术1] | [N] | [X%] | [项目A, 项目B] |
| [技术2] | [N] | [X%] | [项目C] |

### 技术趋势洞察

- **趋势1**：[描述观察到的技术趋势]
- **趋势2**：[描述观察到的技术趋势]

---

## 共性模式识别

### 架构共性

多个项目共同采用的架构模式：
1. **[模式名称]**：[描述]
   - 采用项目：[列举]
   - 优势分析：[分析]

### 功能共性

多个项目都实现的核心功能：
1. **[功能名称]**：[描述]
   - 实现方式差异：[对比]

### 文档共性

文档编写的共同特点：
- [观察到的文档模式]

---

## 项目对比分析

### 功能对比矩阵

| 功能 | 项目1 | 项目2 | 项目3 | 最优实现 |
|:-----|:-----|:-----|:-----|:---------|
| [功能1] | ✅ | ✅ | ❌ | [分析] |
| [功能2] | ✅ | ❌ | ✅ | [分析] |

### 架构对比

| 维度 | 项目1 | 项目2 | 项目3 | 值得学习 |
|:-----|:-----|:-----|:-----|:---------|
| 目录结构 | [描述] | [描述] | [描述] | [推荐] |
| 模块化 | [描述] | [描述] | [描述] | [推荐] |

### 代码质量对比

| 项目 | 代码组织 | 文档 | 测试 | 综合评分 |
|:-----|:---------|:-----|:-----|:---------|
| 项目1 | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | ⭐⭐☆☆☆ | B+ |
| 项目2 | ⭐⭐⭐☆☆ | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | B |

---

## 深度剖析（精选项目）

### 项目 A: [仓库名]

#### 为什么值得深入研究

[说明选择这个项目进行深度剖析的原因]

#### 架构亮点

- [亮点1]
- [亮点2]

#### 可借鉴的设计

1. **[设计点1]**：[描述可借鉴之处]
2. **[设计点2]**：[描述可借鉴之处]

### 项目 B: [仓库名]

[同上结构]

---

## 启发与建议

### 对本地项目的启发

#### 可直接借鉴

1. **[方面1]**
   - **来源**：[项目A/项目B]
   - **做法**：[描述具体做法]
   - **本地应用**：[如何应用到本地项目]
   - **优先级**：🔴 高 / 🟡 中 / 🟢 低
   - **预计工作量**：[X 小时]

#### 需要进一步探索

1. **[技术/模式]**
   - **为什么**：[说明价值]
   - **调研方式**：[如何调研]
   - **预期收益**：[说明]

### 最佳实践总结

从多个项目中提炼的最佳实践：
1. **[实践1]**：[描述]
2. **[实践2]**：[描述]

---

## 项目推荐

### 不同场景推荐

| 场景 | 推荐项目 | 理由 |
|:-----|:---------|:-----|
| 学习参考 | [项目名] | [理由] |
| 生产使用 | [项目名] | [理由] |
| 二次开发 | [项目名] | [理由] |
| 特定需求 | [项目名] | [理由] |

### 快速决策指南

- **如果你需要 X** → 推荐 [项目A]
- **如果你需要 Y** → 推荐 [项目B]
- **如果你需要 Z** → 推荐 [项目C]

---

## 附录

### 完整仓库列表

#### 深度研究的项目

1. **[项目名]** - [GitHub URL]
   - 描述：[描述]
   - 技术栈：[列举]
   - 最后更新：[日期]

#### 仅浏览的项目

1. **[项目名]** - [GitHub URL]
   - 相关度：⭐⭐☆☆☆

### 参考资源

- [相关文档链接]
- [相关文章链接]

---

**报告生成时间**：YYYY-MM-DD HH:MM
**研究者**：Claude Code + repo-research skill
**搜索工具**：find-skills skill

Step 6: Session Report

## 主题研究完成

**搜索主题**：[主题关键词]

**搜索结果**：找到 [N] 个相关仓库，深度分析了 [M] 个

**核心发现**：
1. [发现1]
2. [发现2]
3. [发现3]

**推荐项目**：
- 学习参考：[项目A]
- 生产使用：[项目B]

**详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

Original Research Modes

(The following content remains unchanged...)

Step 1: Prepare the research environment

1.0 Read the configuration file

⚠️ Important: First read the configuration file to determine the output directory.

# 读取配置文件逻辑（在开始研究前执行）
import yaml
from pathlib import Path

def get_output_dir():
    """获取输出目录，优先使用配置文件中的设置"""

    # 默认输出目录
    default_output = "./research"

    # 配置文件路径
    skill_dir = Path(__file__).parent  # skill 所在目录
    config_path = skill_dir / "assets" / "config.yaml"

    if not config_path.exists():
        return default_output

    try:
        with open(config_path, 'r', encoding='utf-8') as f:
            config = yaml.safe_load(f)

        output_dir = config.get('research', {}).get('output_dir', '')

        if not output_dir or output_dir.strip() == '':
            return default_output

        # 展开 ~ 和环境变量
        output_dir = Path(output_dir).expanduser()

        # 如果是相对路径，基于当前工作目录
        if not output_dir.is_absolute():
            output_dir = Path.cwd() / output_dir

        return str(output_dir)

    except Exception:
        return default_output

1.1 Create the research directory

Unified directory structure：

research/
└── YYYYMMDD-[topic]/    # 日期+主题目录
    ├── repo-name/       # 研究的仓库（即使是单个仓库也在子目录中）
    ├── repo-b/          # 多仓库时会有多个子目录
    └── [topic-slug]-report.md        # 研究报告

# 单仓库示例：
# ~/Documents/研究笔记/20260213-vibe-working-tutorial/
#     └── vibe-working-tutorial/   <- 仓库内容
#     └── [topic-slug]-report.md

# 多仓库示例：
# ./research/20260213-pdf-tools-comparison/
#     ├── pdf-lib/
#     └── pdfkit/
#     └── [topic-slug]-report.md

Design principle: No matter how many repositories are researched, maintain ${OUTPUT_DIR}/日期-主题/仓库名/ with a unified structure for easier subsequent management and expansion.

Naming format：YYYYMMDD-[topic-slug]

topic-slug: Topic keywords, connected with hyphens, lowercase
Example:20260211-pdf-ocr-comparison、20260212-transcription-study

Topic source(priority from high to low):

User-specified: Provided via the --topic parameter when invoked
Conversational inquiry: Automatically ask the user to enter a short topic description
Automatic inference: Infer from the repository name or research content (fallback)

Use the Bash tool to execute:

⚠️ Important：

First read skills/repo-research/assets/config.yaml to get output_dir
If the configuration file does not exist or output_dir is empty, use the default value ./research
The path supports ~ expansion and relative paths

# Step 1: 读取配置文件获取输出目录
# 默认输出目录
OUTPUT_DIR="./research"

# 检查配置文件是否存在
CONFIG_FILE="skills/repo-research/assets/config.yaml"
if [ -f "$CONFIG_FILE" ]; then
    # 使用 grep 简单提取 output_dir（避免依赖 Python/yaml）
    CONFIG_OUTPUT=$(grep -E "^\s*output_dir:" "$CONFIG_FILE" | head -1 | sed 's/.*output_dir:[[:space:]]*//')
    # 移除引号
    CONFIG_OUTPUT=$(echo "$CONFIG_OUTPUT" | tr -d "\"'")
    # 如果非空，使用配置值
    if [ -n "$CONFIG_OUTPUT" ] && [ "$CONFIG_OUTPUT" != '""' ]; then
        # 展开 ~ 为用户目录
        OUTPUT_DIR="${CONFIG_OUTPUT/#\~/$HOME}"
    fi
fi

# Step 2: 如果是相对路径，基于当前工作目录
if [[ "$OUTPUT_DIR" != /* ]]; then
    OUTPUT_DIR="${PWD}/${OUTPUT_DIR}"
fi

# Step 3: 创建研究目录
REPO_DATE=$(date +%Y%m%d)
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

RESEARCH_DIR="${OUTPUT_DIR}/${REPO_DATE}-${TOPIC_SLUG}"
mkdir -p "${RESEARCH_DIR}"
cd "${RESEARCH_DIR}"

echo "研究目录已创建: ${RESEARCH_DIR}"

Ask about the topic conversationally：

"Please provide a short topic description for this research (used for directory naming, e.g. pdf-ocr、agent-framework）："

1.2 Clone the repository

⚠️ Important: Whether it is a single repository or multiple repositories, clone them uniformly into subdirectories to keep the directory structure consistent.

# 统一方式：所有仓库都克隆到子目录
# 这样可以保持 research/日期-主题/ 目录结构的一致性
# 单仓库和多仓库的区别只在于克隆的次数

for url in "${URLS[@]}"; do
    repo_name=$(basename "$url" .git)
    git clone --depth 1 "$url" "$repo_name"
done

# 单仓库示例（实际也是克隆到子目录）：
# research/20260213-vibe-working-tutorial/
#     └── vibe-working-tutorial/   <- 仓库内容
#     └── [topic-slug]-report.md                <- 研究报告

# 多仓库示例：
# research/20260213-pdf-tools-comparison/
#     └── pdf-lib/                 <- 仓库A
#     └── pdfkit/                  <- 仓库B
#     └── [topic-slug]-report.md                <- 研究报告

Step 2: Basic analysis (for each repository)

2.1 Identify the project type

Feature	Project type	Analysis focus
`package.json`	Node.js/Frontend	Dependencies, scripts, build configuration
`requirements.txt`/`pyproject.toml`	Python	Virtual environment, dependency management
`go.mod`	Go	Module structure, dependencies
`Cargo.toml`	Rust	Edition, features, dependencies
`SKILL.md`	Claude Skill	Skill definitions, frontmatter

2.2 Prioritize reading core files

# 必读文件（按优先级）
README.md          # 项目说明、快速开始
LICENSE            # 许可证
package.json/pyproject.toml/go.mod  # 依赖元数据

2.3 Project structure analysis

Use the Glob tool to explore:

glob "**/*"           # 所有文件
glob "**/*.md"        # 文档
glob "src/**/*.ts"    # 源代码
glob "tests/**/*"     # 测试

2.4 Technology stack identification

Frontend: React/Vue/Svelte/Next.js/Nuxt + state management + styling solution
Backend: Node.js/Python/Go/Rust + framework + ORM
Toolchain：Vite/Webpack + Jest/Pytest + ESLint/Prettier

Step 3: Multi-repository comparative analysis (multi-repository mode)

3.1 Comparison dimensions

Dimension	Comparison content	Inspiration points
Architecture design	Directory structure, module division	Which organizational approaches are worth learning from
Feature implementation	Core features, API design	Different implementation approaches for similar features
Technology selection	Frameworks, dependencies, toolchain	Why these technologies were chosen
Documentation quality	README, comments, API documentation	Differences in documentation writing styles
Code style	Naming, structure, patterns	Which style is clearer

3.2 Commonality extraction

Identify commonalities among multiple repositories:

Common technical choices (e.g., both use Markdown as the format)
Common design patterns (e.g., both use a plugin architecture)
Common problem-solving approaches

3.3 Difference Analysis

Identify key differences and their causes:

Why A uses Markdown while B uses JSON
Why A has tests while B does not
The pros and cons of different implementation approaches

Step 4: Local Project Comparison (Inspiration Mode)

4.1 Identify Local Projects

Ask in the conversation：

"Do you need to compare with a local project? If so, please provide the project path (relative or absolute)."

Common local project types:

./test/de-ai-polish - Local skills
./skills/xxx - Existing skills
./test/yyy - Test projects

4.2 Difference Analysis Framework

Analysis Item	External Repository	Local Project	Difference	Inspiration
Directory Structure	[Description]	[Description]	[Difference Point]	[What Can Be Learned]
Core Features	[Description]	[Description]	[Difference Point]	[What Can Be Added]
Documentation Approach	[Description]	[Description]	[Difference Point]	[What Can Be Improved]
Detection Rules	[List]	[List]	[Difference Point]	[What Can Be Learned]

4.3 Heuristic Questions

Answer the following questions during comparison:

Functionality
- What features does the external repository have that I do not?
- What features do I have that the external repository does not?
- Which features can be integrated?
Architecture
- Is the external repository's directory structure clearer?
- Is the module division approach worth learning from?
- Is the configuration approach more flexible?
Implementation
- How does the organization of detection rules differ?
- What are the pros and cons of the report generation format?
- What can be learned from the user interaction approach?
Documentation
- Is the README structure easier to understand?
- Are the examples more abundant?
- Is the API documentation more complete?

Step 5: Generate Report

5.1 Single Repository Report Structure

Use assets/report-template.md as the template.

5.2 Multi-Repository Comparison Report Structure

Use assets/comparison-template.md as the template.

5.3 Heuristic Report Structure

# [研究主题] 启发式分析报告

> 研究日期：YYYY-MM-DD
> 研究仓库：[列出所有仓库]
> 对比项目：[本地项目路径]
> 报告路径：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

---

## 核心发现

### 一句话总结

[用一句话概括最关键的启发]

---

## 对比分析

### 功能对比

| 功能 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| [功能1] | ✅ | ✅ | ❌ | [建议] |
| [功能2] | ✅ | ❌ | ✅ | [分析] |

### 架构对比

| 维度 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-----|:------|:------|:---------|:-----|
| 目录结构 | [描述] | [描述] | [描述] | [建议] |
| 模块划分 | [描述] | [描述] | [描述] | [建议] |

### 规则/检测方式对比

| 检测项 | 仓库A | 仓库B | 本地项目 | 启发 |
|:-------|:------|:------|:---------|:-----|
| [规则1] | [实现] | [实现] | [实现] | [可学习] |

---

## 具体启发

### 可直接借鉴的方面

1. **[方面1]**
   - **外部做法**：[描述]
   - **本地现状**：[描述]
   - **改进建议**：[具体建议]
   - **优先级**：高/中/低

2. **[方面2]**
   - **外部做法**：[描述]
   - **本地现状**：[描述]
   - **改进建议**：[具体建议]
   - **优先级**：高/中/低

### 需要进一步探索的方面

1. **[方面1]**：[为什么值得探索]
2. **[方面2]**：[为什么值得探索]

---

## 行动建议

### 立即可做的改进

- [ ] [改进1] - 预计时间：[X小时]
- [ ] [改进2] - 预计时间：[X小时]

### 需要进一步调研的

- [ ] [调研项1] - 调研方式：[如何调研]
- [ ] [调研项2] - 调研方式：[如何调研]

---

## 附录

### 仓库详细信息

- **仓库A**：[名称](URL) - [一句话描述]
- **仓库B**：[名称](URL) - [一句话描述]

### 参考链接

- [相关文档]
- [相关文章]

5.4 Session Reporting Format

## 研究完成

**研究仓库**：
- [仓库名A]：[一句话描述]
- [仓库名B]：[一句话描述]

**对比项目**：[本地项目路径]

**核心启发**：
1. [启发1]
2. [启发2]
3. [启发3]

**立即可做的改进**：
- [ ] [改进1]
- [ ] [改进2]

**详细报告已保存至**：`./research/YYYYMMDD-[topic-slug]/[topic-slug]-report.md`

Best Practices

Research Strategy

Inspiration First: The ultimate purpose of research is "how does this help me"
Comparison-Driven: Discover differences through comparison, gain inspiration through differences
Specific and Actionable: Insights must be transformed into concrete improvement suggestions

Principles for Extracting Insights

Learn from differences: Different implementation approaches often have different considerations
Summarize from commonalities: The common choices of multiple repositories often have their reasons
Gain insight from details: Small details may reflect design philosophy

Resources

assets/

report-template.md: Single repository report template
comparison-template.md: Multi-repository comparison report template
topic-research-template.md: Topic-driven search research report template (new)

Advanced Features (v0.4.0)

Drawing on the implementation approach of Zread MCP to enhance local analysis capabilities.

1. Code Semantic Search

Use locally cloned repositories to perform in-depth code search.

Trigger Method

Activated when the user expresses the following needs:

"Search for function X"
"Find class Y"
"See how this project implements Z"
Directly use the --search parameter

Usage

# 搜索函数定义
/repo-research https://github.com/user/repo --search="function:parse*"

# 搜索类定义
/repo-research https://github.com/user/repo --search="class:*Handler"

# 搜索导入
/repo-research https://github.com/user/repo --search="import:react"

# 搜索特定模式
/repo-research https://github.com/user/repo --search="pattern:console\.log"

Internal Implementation

Call the scripts/search.py in CodeSearcher class:

Use the Grep tool for pattern matching
Supports multiple languages: Python, JavaScript, TypeScript, Go, Rust, Java
Supports multiple patterns: function, class, import, doc, pattern

2. Deep Code Analysis

Go beyond basic analysis to provide deep insights at the architecture and quality levels.

Analysis Types

Type	Description	Trigger Parameter
Architecture Analysis	Directory structure, module division, entry files, architecture patterns	`--analyze=architecture`
Quality Analysis	Code statistics, comment ratio, technical debt, potential issues	`--analyze=quality`
Full Analysis	Includes both architecture and quality dimensions	`--analyze=full`

Usage

# 架构分析
/repo-research https://github.com/user/repo --analyze=architecture

# 质量分析
/repo-research https://github.com/user/repo --analyze=quality

# 完整分析
/repo-research https://github.com/user/repo --analyze=full

Internal Implementation

Architecture Analyzer (scripts/analyzer/architecture.py):
- Directory structure analysis
- Entry file identification
- Module/package structure identification
- Configuration file detection
- Architecture pattern detection (MVC, microservices, plugin, monorepo)
Quality Analyzer (scripts/analyzer/quality.py):
- Code statistics (lines of code, language distribution)
- Comment coverage analysis
- Technical debt detection (TODO, FIXME, deprecated)
- Issue detection (hardcoded secrets, console.log, large files)

3. Intelligent Q&A

Use the LLM capabilities of Claude Code to answer natural language questions about the repository.

Trigger Method

Activated when the user expresses the following needs:

"What does this project do?"
"How do I use this project?"
"What is the architecture like?"
"What are the main modules?"
Directly use the --ask parameter

Usage

# 询问项目概述
/repo-research https://github.com/user/repo --ask="这个项目是做什么的？"

# 询问使用方法
/repo-research https://github.com/user/repo --ask="如何使用这个项目？"

# 询问架构
/repo-research https://github.com/user/repo --ask="架构是怎样的？"

Internal Implementation

Question Classification (scripts/qa.py in QuestionClassifier):
- Intent recognition: overview, architecture, usage, api, dependencies
- Entity extraction: feature names, component names, file names
- context determination: which files need to be read
answer generation:
- use Grep/Glob to search relevant code
- use read_file to read key files
- combine with Claude Code's LLM capabilities to generate natural language answers

4. Combined use

Advanced features can be used in combination to achieve more powerful analysis capabilities:

# 搜索 + 分析
/repo-research https://github.com/user/repo --search="function:parse*" --analyze=architecture

# 问答 + 报告
/repo-research https://github.com/user/repo --ask="这个项目如何使用？" --output=report

scripts/ directory structure

scripts/
├── __init__.py           # 模块导出
├── search.py             # 语义搜索
├── qa.py                 # 智能问答
├── architecture.py       # 架构分析
├── quality.py            # 质量分析
└── security.py           # 安全分析 (v0.5.0 新增)

Security analysis module (v0.5.0)

Designed based on the OWASP Agentic AI Top 10 and common vulnerability patterns, used to identify potential malicious code or security risks in skills.

Trigger method

# 安全分析模式
/repo-research https://github.com/user/skill --analyze=security

# 完整分析（包含安全）
/repo-research https://github.com/user/skill --analyze=full

Detection capabilities

Category	Detection content	Risk level
Command execution	`os.system`, `subprocess`, `eval()`, `exec()`	🔴 High
Sensitive file access	read/write `~/.ssh/`, `~/.aws/`, `.env` , etc.	🔴 High
Network exfiltration	HTTP POST, WebSocket, data upload	🟡 Medium
Code obfuscation	`base64.b64decode`, `chr()` concatenation, etc.	🔴 High
Privilege escalation	`sudo`, `chmod 777`, modify PATH	🔴 High
Hardcoded credentials	API Key、Token、Password	🔴 High
Download and execute	`curl	bash`,` wget
Persistence	crontab, systemd, LaunchAgents	🟡 Medium
Skill-specific	Install hooks, MCP server risks	🟡 Medium

Risk level

Level	Condition	Recommendation
🔴 critical	Presence of command execution, download and execute, etc.	Strongly not recommended for use; a full audit is required
🟠 high	Multiple high-risk findings or hardcoded credentials	Use after audit, restrict permissions
🟡 medium	A small number of medium-risk findings	Check before use, verify in a test environment
🟢 low	Only low-risk or no findings	Safe to use

Usage example

# 分析一个 skill 的安全性
/repo-research https://github.com/example/skill --analyze=security

# 在研究报告对话框中，会自动包含安全分析章节
# 如果检测到高风险，会有明显的警告提示

Future plans

dependency analysis module
performance analysis module
a more intelligent question-answering system

About this skill

Dependency Management

Configuration

Configuration File Location

Quick Configuration

Configuration Item Description

Configuration Reading Logic

Default Behavior (No Configuration File)

Quick Start

Configuration

Configuration File

Configuration File Location

Configuration Example

Environment Variable Override

Output Directory Structure

Workflow

Mode Selection

Topic-driven Search Research Mode

Trigger Conditions

Workflow

Step 0: Dependency Check

Step 1: Use find-skills to Search for Relevant Repositories

Step 2: Organize Search Results

Step 3: User Confirmation and Filtering

Step 4: Batch Cloning and Parallel Analysis

4.1 Create Research Directory

4.2 Batch Cloning

4.3 Parallel Analysis

Step 5: Generate Topic Comprehensive Report

Report Structure

Step 6: Session Report

Original Research Modes

Step 1: Prepare the research environment

1.0 Read the configuration file

1.1 Create the research directory

1.2 Clone the repository

Step 2: Basic analysis (for each repository)

2.1 Identify the project type

2.2 Prioritize reading core files

2.3 Project structure analysis

2.4 Technology stack identification

Step 3: Multi-repository comparative analysis (multi-repository mode)

3.1 Comparison dimensions

3.2 Commonality extraction

3.3 Difference Analysis

Step 4: Local Project Comparison (Inspiration Mode)

4.1 Identify Local Projects

4.2 Difference Analysis Framework

4.3 Heuristic Questions

Step 5: Generate Report

5.1 Single Repository Report Structure

5.2 Multi-Repository Comparison Report Structure

5.3 Heuristic Report Structure

5.4 Session Reporting Format

Best Practices

Research Strategy

Principles for Extracting Insights

Resources

assets/

Advanced Features (v0.4.0)

1. Code Semantic Search

Trigger Method

Usage

Internal Implementation

2. Deep Code Analysis

Analysis Types

Usage

Internal Implementation

3. Intelligent Q&A

Trigger Method

Usage

Internal Implementation

4. Combined use

scripts/ directory structure

Security analysis module (v0.5.0)

Trigger method

Detection capabilities

Risk level

Usage example