AgentSkillsCN

research-retrieval

搜索外部文档（网页、API文档、学术论文），并为开发工作生成实用的摘要。在探索新技术、理解第三方API、研究最佳实践，或为技术决策搜集信息时使用此方法。这有助于减少“幻觉”现象，同时拓展智能体的知识储备。

SKILL.md
--- frontmatter
name: research-retrieval
description: Search external documentation (web pages, API docs, papers) and generate useful summaries for development. Use when investigating new technologies, understanding third-party APIs, researching best practices, or gathering information for technical decisions. Reduces hallucinations and expands agent knowledge.
license: MIT
metadata:
  author: AC Framework
  version: "1.0"

Research & Retrieval

External knowledge search, documentation retrieval, and synthesis for informed development decisions.

When to Use This Skill

Use this skill when:

  • •Investigating new technologies, libraries, or frameworks
  • •Understanding third-party APIs and their capabilities
  • •Researching best practices for a specific problem
  • •Gathering information for architecture decisions
  • •Need to verify facts or current information
  • •Exploring solutions to unfamiliar problems

Instructions

Step 1: Define Research Goals

  1. •

    Clarify what you need to know:

    • •Specific technical question
    • •Comparison of technologies
    • •Implementation approach
    • •Best practices
  2. •

    Identify sources:

    • •Official documentation
    • •API references
    • •Technical blogs
    • •Research papers
    • •GitHub repositories
    • •Stack Overflow
  3. •

    Set scope boundaries:

    • •Time period (recent vs. historical)
    • •Version specificity
    • •Language/framework constraints

Step 2: Search and Retrieve

Official Documentation:

code
Priority sources:
1. Official docs (docs.{service}.com)
2. API reference
3. Getting started guides
4. Best practices
5. Changelog/release notes

Technical Blogs & Articles:

code
Quality indicators:
- Recent publication date
- Author expertise/credentials
- Code examples included
- Community engagement
- Updated for current versions

Research Papers (for advanced topics):

code
Use when:
- Novel algorithms needed
- Performance optimizations
- Academic foundations
- Cutting-edge techniques

GitHub Repositories:

code
Evaluate by:
- Stars/forks (popularity)
- Recent commits (maintenance)
- Issue resolution (support)
- Documentation quality
- Test coverage

Step 3: Evaluate Sources

Credibility Checklist:

  • • Authoritative source (official > third-party)
  • • Up-to-date information
  • • Well-explained with examples
  • • Community-validated (comments, issues)
  • • Version compatibility noted

Red Flags:

  • •Outdated documentation
  • •Unexplained "magic" solutions
  • •No code examples
  • •Deprecated approaches
  • •Unsupported claims

Step 4: Extract Key Information

For each relevant source, extract:

markdown
## Source: [Title/URL]

**Relevance**: [High/Medium/Low]
**Date**: [Publication date]
**Version**: [Software version, if applicable]

### Key Points

1. [Important finding 1]
2. [Important finding 2]
3. [Important finding 3]

### Code Examples

\`\`\`[language]
// Relevant code snippet
\`\`\`

### Warnings/Caveats

- [Known issues or limitations]
- [Breaking changes]
- [Performance considerations]

### References

- [Link 1]
- [Link 2]

Step 5: Synthesize Findings

Compare approaches:

markdown
## Technology Comparison: [Topic]

### Option A: [Technology A]

**Pros**:
- Advantage 1
- Advantage 2

**Cons**:
- Disadvantage 1
- Disadvantage 2

**Best for**: [Use cases]

### Option B: [Technology B]

**Pros**:
- Advantage 1
- Advantage 2

**Cons**:
- Disadvantage 1
- Disadvantage 2

**Best for**: [Use cases]

### Recommendation

[Your recommendation with justification]

Synthesize best practices:

markdown
## Best Practices: [Topic]

Based on [N] sources, consensus on:

### Do's
1. [Recommended approach 1]
2. [Recommended approach 2]

### Don'ts
1. [Anti-pattern 1]
2. [Anti-pattern 2]

### Trade-offs
- [Decision point]: [Option A] vs [Option B]
  - Choose A when: [conditions]
  - Choose B when: [conditions]

Step 6: Generate Actionable Steps

Convert research into implementation steps:

markdown
## Implementation Guide: [Topic]

### Prerequisites
- [Requirement 1]
- [Requirement 2]

### Step-by-Step

1. **Setup**
   - [Action 1]
   - [Action 2]

2. **Configuration**
   - [Action 3]
   - [Action 4]

3. **Implementation**
   - [Action 5]
   - [Action 6]

4. **Testing**
   - [Action 7]

### Common Pitfalls
- [Pitfall 1] → [Solution]
- [Pitfall 2] → [Solution]

Step 7: Store for Reuse

Save findings in references/ directory:

code
references/
├── README.md (index of all references)
├── api/
│   ├── stripe-api-2024-01.md
│   └── openai-api-best-practices.md
├── libraries/
│   ├── react-server-components.md
│   └── state-management-comparison.md
└── patterns/
    ├── authentication-patterns.md
    └── caching-strategies.md

Step 8: Link to OpenSpec

Reference research in specs:

markdown
## Specification: [Feature]

### Research References

- [Authentication Patterns](../references/patterns/authentication-patterns.md)
- [Stripe API Integration](../references/api/stripe-api-2024-01.md)

### Decisions Based on Research

1. **Use JWT for authentication**
   - Rationale: [Summary of research findings]
   - Sources: [Links to references]

2. **Implement Redis caching**
   - Rationale: [Performance benchmarks from research]
   - Sources: [Links to references]

Output Format

After research is complete:

code
## Research Summary: [Topic]

**Sources Consulted**: [N]
**Date**: [Research date]
**Confidence**: [High/Medium/Low]

### Executive Summary

[2-3 sentence overview of findings]

### Key Findings

1. [Finding 1 with source]
2. [Finding 2 with source]
3. [Finding 3 with source]

### Recommendations

1. [Actionable recommendation 1]
2. [Actionable recommendation 2]

### Implementation Steps

[Step-by-step guide based on research]

### References Stored

- references/[category]/[filename].md
- [Link to full research document]

### Uncertainties/Gaps

- [What still needs investigation]
- [Questions that remain unanswered]

Guardrails

  • •Verify critical information - Cross-reference multiple sources
  • •Check publication dates - Avoid outdated information
  • •Prefer official docs - Authoritative over anecdotal
  • •Acknowledge uncertainty - Be clear when information is incomplete
  • •Document sources - Always cite where information came from
  • •Focus on actionable info - Avoid research rabbit holes

Search Strategies

Error Messages:

code
"[exact error message]" + [technology name]

Feature Comparisons:

code
[technology A] vs [technology B] 2024
[technology A] alternative

Best Practices:

code
[technology] best practices
[technology] common pitfalls

Implementation Guides:

code
[technology] getting started tutorial
[technology] example project

Requirements

  • •Web search capability
  • •Access to documentation sites
  • •Ability to evaluate source credibility
  • •Understanding of the domain being researched

See Also

  • •context-synthesizer - Integrate research into project context
  • •spec-clarification - Use research to clarify requirements
  • •documentation - Document findings
  • •brainstorming - Generate ideas based on research