190 lines
6.8 KiB
Markdown
190 lines
6.8 KiB
Markdown
---
|
|
name: local-research
|
|
description: "This skill should be used when performing codebase research with markdown documentation persistence. Triggered by phrases like [local research], [quick research], [load local research], [init local research], [read local research ...]."
|
|
---
|
|
|
|
# Local Research
|
|
|
|
## Overview
|
|
|
|
Perform comprehensive codebase research with persistent markdown documentation stored in `~/workspace/llm/research/`. This skill integrates multiple research tools including fast-repo-context skill, knowledge graph queries, and external resources to create structured research documentation.
|
|
|
|
Use absolute file path in research document for easy share across different projects/repos.
|
|
|
|
### Automation Script
|
|
|
|
The skill includes an automation script at `~/.claude/skills/local-research/scripts/research_ops.py` that handles:
|
|
- Generating descriptive research names from user queries
|
|
- Creating research directories and markdown files with timestamps
|
|
- Listing and locating existing research files by keywords
|
|
- Providing CLI interface for all research operations
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- Need to research and analyze codebase structure and patterns
|
|
- Want to create persistent research documentation
|
|
- Need to load previous research findings
|
|
- User says "local research", "quick research", or "load local research"
|
|
|
|
## Core Workflow
|
|
|
|
### Research Generation Process (when user explicitly requests new research)
|
|
|
|
1. **Generate Research Name**: Create descriptive research name based on user input as `<user-query>`, user input may contain typos, improve it.
|
|
2. **Create Research File**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"`
|
|
3. **Ask Clarifying Questions**: Ask user for more details about research scope
|
|
4. **Execute Research Workflow**: Use integrated tools to gather information
|
|
5. **Document Findings**: Write results to research markdown file, use absolute file path when writting, do not use `~` path abbreviation.
|
|
|
|
### Loading Research Process (when user mention load or update doc, or provided doc keywords)
|
|
|
|
When user requests to "load local research" or similar:
|
|
1. **List Research Files**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py list`
|
|
2. **Identify Target**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py locate <keywords>`
|
|
3. **Load Content**: Read and display the summary of relevant research markdown file
|
|
|
|
## Research Tools and Methods
|
|
|
|
### Primary Research Tools
|
|
|
|
1. **Fast Context Skill** (`fast-repo-context`):
|
|
- load fast-repo-context skill
|
|
- Use for comprehensive codebase understanding
|
|
- Leverages repomix-generated XML for efficient searching
|
|
|
|
2. **Knowledge Graph** (`kg`):
|
|
- Query related keywords and existing research
|
|
- Use `mcp__kg__query_graph` with semantic search
|
|
- Set `group_id` to organize research by project/topics
|
|
|
|
3. **External Resources**:
|
|
- **Brightdata**: Use `mcp__brightdata__search_engine` for web research
|
|
- **GitHub**: Use `mcp__github__search_code` or `mcp__github__search_repositories` for external code reference
|
|
|
|
### Research Execution Order
|
|
|
|
1. **Initialize Research Environment**:
|
|
```bash
|
|
python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"
|
|
```
|
|
|
|
2. **Fast Context Analysis**:
|
|
- Extract code structure, patterns, and key files
|
|
- Document findings in research file
|
|
|
|
3. **Knowledge Graph Integration**:
|
|
- Query `kg` for related information
|
|
- Use semantic search with research keywords
|
|
- Integrate findings into research documentation
|
|
|
|
4. **External Research** (if needed):
|
|
- Use Brightdata for web research on related topics
|
|
- Use GitHub tools for external examples and best practices
|
|
- Add external insights to research file
|
|
|
|
## Research Documentation Structure
|
|
|
|
Each research markdown file should follow this structure:
|
|
|
|
```markdown
|
|
# <Research Name>
|
|
|
|
- **Created**: <timestamp>
|
|
- **Research Query**: <original user input>
|
|
|
|
## Executive Summary
|
|
<brief overview of findings>
|
|
|
|
## Codebase Analysis
|
|
<findings from fast-repo-context>
|
|
|
|
## Knowledge Graph Insights
|
|
<related information from kg queries>
|
|
|
|
## External Research
|
|
<findings from web/github research if applicable>
|
|
|
|
## Key Findings
|
|
<important discoveries and insights>
|
|
|
|
## Recommendations
|
|
<actionable recommendations based on research>
|
|
|
|
## Files Referenced
|
|
<list of key files analyzed>
|
|
|
|
## Next Steps
|
|
<suggested follow-up actions>
|
|
```
|
|
|
|
- Note: file path in the research doc must use absolute path, do not use `~` abbreviation, because this doc will be shared across different project/repos.
|
|
|
|
## Loading Research
|
|
|
|
When user wants to load existing research:
|
|
|
|
1. **Available Research**: List all research files with timestamps
|
|
2. **Search Matching**: Match user keywords to research names/content
|
|
3. **Display Findings**: Present the complete research file content
|
|
|
|
### Script Commands
|
|
|
|
```bash
|
|
# Create new research file
|
|
python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"
|
|
|
|
# List all research files (sorted by timestamp)
|
|
python3 ~/.claude/skills/local-research/scripts/research_ops.py list
|
|
|
|
# Locate research file by keywords
|
|
python3 ~/.claude/skills/local-research/scripts/research_ops.py locate <keywords...>
|
|
|
|
# Read specific research file
|
|
cat ~/workspace/llm/research/<research-name>-<timestamp>.md
|
|
```
|
|
|
|
## Integration with Other Skills
|
|
|
|
### Fast Context Integration
|
|
- Always invoke `fast-repo-context` skill for codebase analysis
|
|
- Follow its mandatory checklist: check repomix freshness, search XML, then optionally KG
|
|
- Document steps completed in research file
|
|
|
|
### Knowledge Graph Integration
|
|
- Use consistent `group_id` for related research projects
|
|
- Store research summaries in KG for future retrieval
|
|
- Query KG before starting new research to avoid duplication
|
|
|
|
## Research Naming Conventions
|
|
|
|
Generate descriptive research names:
|
|
- Convert user input to kebab-case
|
|
- Include domain/technology focus
|
|
- Example inputs to names:
|
|
- "analyze authentication system" → "authentication-system-analysis"
|
|
- "react performance issues" → "react-performance-investigation"
|
|
- "api design patterns" → "api-design-patterns-research"
|
|
|
|
## Error Handling
|
|
|
|
- If research directory creation fails, check permissions and path
|
|
- If fast-repo-context claude skill is unavailable, fall back to direct code search
|
|
- If external resources are unreachable, continue with internal research
|
|
- Always document any limitations or issues encountered
|
|
|
|
# Example
|
|
|
|
<example>
|
|
<user>
|
|
please load local research on "authentication system analysis" and update the document with any new findings.
|
|
</user>
|
|
|
|
<assistant>
|
|
```bash
|
|
python3 ~/.claude/skills/local-research/scripts/research_ops.py locate authentication system analysis
|
|
```
|
|
Good, found the research file at `<file-path>`. Now loading the content and summarizing the key points for you.
|
|
</assistant>
|
|
</example>
|