skill-deep-dive

Category: Development & Coding | Uploader: davethegut | Downloads: 0 | Version: v1.0（Latest）

Research any topic within a GitHub repo and generate a polished HTML deep-dive document. Use when the user wants to learn about a codebase feature, understand architecture, onboard to a new area, or says "deep dive into ..." or "teach me about ...".

Changelog: Source: GitHub https://github.com/davethegut/cursor-skill-deep-dive

Directory Structure

Current level: Root

📁 examples/
- 📄 sample-deep-dive-output.html 19.1 KB
📄 AGENTS.md 689 B
📄 LICENSE 1.0 KB
📄 README.md 8.6 KB
📄 SKILL.md 6.9 KB
📄 template.html 8.9 KB

SKILL.md

---
name: skill-deep-dive
description: Research any topic within a GitHub repo and generate a polished HTML deep-dive document. Use when the user wants to learn about a codebase feature, understand architecture, onboard to a new area, or says "deep dive into ..." or "teach me about ...".
triggers:
  - "deep dive into"
  - "teach me about"
  - "I want to learn about"
  - "generate a reference doc"
  - "onboard me to"
  - "explore the codebase"
  - "how does X work in repo"
---

# Deep-Dive Researcher

Research a topic inside a GitHub repository and produce a self-contained HTML reference document. Works with any repo accessible via the `gh` CLI.

## When to Use

- "Deep dive into Attack Discovery"
- "Teach me about the workflows engine in elastic/kibana"
- "I want to learn about the router in remix-run/remix"
- "Generate a reference doc for the detection rules engine"
- "Onboard me to [feature] in [repo]"

## Prerequisites

- `gh` CLI installed and authenticated (`gh auth status`)
- If exploring a local clone, the repo must be checked out in the workspace

## Process

### Step 1: Discovery

Ask the user three things conversationally (do not assume defaults without asking):

1. **Topic** — What do you want to learn about? (e.g., "Attack Discovery", "the router", "plugin lifecycle")
2. **Repository** — Which GitHub repo? (e.g., `elastic/kibana`, `vercel/next.js`). If there is a local clone in the workspace, confirm that the user wants to use it.
3. **Output directory** — Where to save the HTML file? Suggest `./deep-dives/` as the default.

### Step 2: Research

Gather data from multiple angles. Run searches in parallel where possible.

#### 2a. Find the main directory/plugin

Identify the primary directory for the topic. Strategies:

- **Local clone**: Search for directories, plugin manifests, or package.json files matching the topic name.
- **GitHub search**: `gh search code "<topic>" --repo owner/name --limit 20` to find relevant files.
- **README scan**: Look for README.md files in candidate directories.

Once you find the main directory, note it — all subsequent searches scope to it first.

#### 2b. Code architecture

From the main directory:

- Read the top-level README, if present.
- Identify entry points: plugin class, index.ts, main exports.
- Map the directory structure (list key subdirectories and what they contain).
- Read key type definitions, interfaces, and constants.
- Follow the primary data flow: where does execution start, what services are called, what gets returned?

Aim for breadth first — read file listings and exports before diving into individual files. Prioritize public API surfaces, route definitions, and type files.

#### 2c. Documentation and context

- Search for markdown docs: `find <dir> -name "*.md"` or `gh search code "filename:README.md <topic>" --repo owner/name`
- Check for architecture decision records, design docs, or CONTRIBUTING guides.
- Look for comments in key files that explain design intent.

#### 2d. Issues and PRs

Gather recent activity for historical context:

```bash
gh issue list --repo owner/name --search "<topic>" --limit 10 --json number,title,state,url
gh pr list --repo owner/name --search "<topic>" --limit 10 --state merged --json number,title,url,mergedAt
```

Focus on epics, design discussions, and recent merged PRs that reveal intent and direction.

#### 2e. Configuration and setup

- How is the feature enabled/disabled? (feature flags, config files, environment variables)
- What dependencies does it require?
- How does a developer run or test it locally?

### Step 3: Synthesis

Organize findings into the following sections. Skip sections that don't apply; add custom sections if the topic warrants it.

| Section | Content |
|---------|---------|
| **Overview** | One-paragraph summary: what it is, what problem it solves, who uses it |
| **Architecture** | Key components, how they connect, data flow. Use HTML diagrams where possible (flow-diagram divs from the template) |
| **Key Files & Directories** | Table: path, description, why it matters |
| **How It Works** | Step-by-step walkthrough of the primary flow |
| **Key Concepts & Types** | Important interfaces, types, enums, constants — with brief explanations |
| **Configuration & Setup** | How to enable, configure, and run locally |
| **Related Issues & PRs** | Table of relevant GitHub activity with links |
| **Further Reading** | Links to READMEs, external docs, related features |

### Step 4: Generate HTML

Read the template at `template.html` (in this skill's directory). It contains the full CSS and page structure with placeholder markers.

Replace the placeholders with generated content:

| Placeholder | Replace with |
|-------------|-------------|
| `{{BADGE}}` | Short category label (e.g., "Deep Dive", "Architecture") |
| `{{TITLE}}` | Page title (e.g., "Attack Discovery — Deep Dive") |
| `{{SUBTITLE}}` | One-line description of the page |
| `{{TOPIC}}` | Topic name for the filename |
| `{{GENERATED_DATE}}` | Current date in YYYY-MM-DD format |
| `{{REPO}}` | Repository name (e.g., `elastic/kibana`) |
| `{{CONTENT}}` | All synthesized sections as HTML (use h2, h3, tables, code blocks, summary-box, etc.) |

**HTML authoring guidelines:**

- Use `<h2>` for top-level sections, `<h3>` for subsections.
- Use `<table>` inside content for structured data (files, types, issues).
- Use `<div class="summary-box">` for key takeaways or callout blocks.
- Use `<code>` for inline code, `<pre><code>` for code blocks.
- Use `<ul>` / `<li>` for lists.
- Keep the page self-contained — no external links for CSS/JS, no images.
- Do NOT use placeholder markers literally in the output — replace every one.

### Step 5: Save and offer

1. Create the output directory if it doesn't exist.
2. Save the file as `<topic-kebab-case>-deep-dive.html` (e.g., `attack-discovery-deep-dive.html`).
3. Tell the user the file path and offer:
   - Open it in the browser to review
   - Refine or expand specific sections
   - Add more detail on a particular area

## Quality Checklist

Before saving, verify:

- [ ] Every section has substantive content (not just placeholders or TODOs)
- [ ] File paths in the "Key Files" table are accurate
- [ ] GitHub links use full URLs (`https://github.com/owner/repo/...`)
- [ ] Code snippets are syntax-highlighted where possible (`<code>` tags)
- [ ] The page renders correctly as a standalone HTML file
- [ ] No external dependencies (CSS, JS, fonts, images)

## Tips

- For large repos, use directory listings and exports to build a mental map before reading individual files. Don't try to read every file.
- If the topic spans multiple plugins or packages, organize the architecture section around the boundaries between them.
- If `gh search code` returns too many results, narrow with filename filters: `gh search code "<topic> filename:index.ts" --repo owner/name`
- When a local clone is available, prefer local file reads over `gh` API calls — they're faster and don't hit rate limits.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

skill-deep-dive

Directory Structure

SKILL.md

Report

Notice