AGENT SKILL

research-expert

Exploratory analysis of repositories and technical sources: dependency map generation (AST parsing), bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis via git log mining, multi-source triangulation, and citation tracking. Use when exploring unfamiliar codebases, researching technical approaches, comparing technologies, analyzing repository structure, or building knowledge bases from source code. Trigger: research, codebase exploration, dependency mapping, technical debt, hot-spot analysis, git mining, triangulation. Do NOT trigger for: debugging specific bugs, writing code, reviewing pull requests, general web research without codebase context (use websearch tool directly).

License 许可
MIT
最近更新
2026-08-27
Stars
★ 1
Forks
0

01 前言 Front Matter

name
research-expert
license
MIT
metadata
{ "author": "Community", "status": "stable", "version": "1.1", "category": "process" }
description
Exploratory analysis of repositories and technical sources: dependency map generation (AST parsing), bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis via git log mining, multi-source triangulation, and citation tracking. Use when exploring unfamiliar codebases, researching technical approaches, comparing technologies, analyzing repository structure, or building knowledge bases from source code. Trigger: research, codebase exploration, dependency mapping, technical debt, hot-spot analysis, git mining, triangulation. Do NOT trigger for: debugging specific bugs, writing code, reviewing pull requests, general web research without codebase context (use websearch tool directly).

02 资源文件 4

03 SKILL.md 正文

Research Expert

Codebase exploration, dependency mapping, tech research and triangulation.

Research Workflow

  1. Define question — what specifically are we trying to learn?
  2. Gather sources — code, docs, git history, external references
  3. Map dependencies — what depends on what?
  4. Identify patterns — architecture style, bounded contexts, anti-patterns
  5. Triangulate — cross-validate across >=3 independent sources
  6. Synthesize — produce structured findings document

Codebase Analysis

# Hotspot analysis — files changed most frequently
git log --format=format: --name-only | sort | uniq -c | sort -nr | head -20

# Code churn — files with most added/deleted lines
git log --numstat --pretty=format: | awk '{a[$3]+=$1+$2} END {for(f in a) print a[f],f}' | sort -nr | head -20

# Dependency map — what imports this package?
grep -r "import.*github.com/example/services" --include="*.go" -l

Dependency Graph Analysis

Entry points -> Core domain -> Infrastructure -> External deps

Identify:
- Circular dependencies (A imports B, B imports A)
- God packages (imported by >20 files)
- Orphans (imported by 0 files — dead code?)

Multi-Source Triangulation

Source Reliability Use For
Source code Highest Behavior, architecture
Tests High Expected behavior, edge cases
Git history High Change frequency, ownership
Documentation Medium Intent, rationale
Issues/PRs Medium Known problems, discussions
External docs Variable API specs, best practices

Constraints

  • NEVER trust documentation over code behavior (code is truth)
  • NEVER draw conclusions from single source (triangulate >=3)
  • ALWAYS verify assumptions by reading actual source code
  • NEVER assume patterns without statistical evidence (grep counts, git stats)

Overview

Conduct exploratory analysis of repositories and technical sources: dependency graph mapping via AST parsing, bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis through git log mining, multi-source triangulation, and citation tracking.

Quick Reference

Analysis Command Insight
Hotspot files git log --name-only sort
Code churn git log --numstat awk sum
Dependencies grep -r "import.*pkg" Which files depend on a given package
Cyclomatic complexity gocyclo ./... High-complexity functions needing refactor
Bounded contexts grep package declarations Module boundaries and cohesion

Workflow

  1. Define the research question explicitly before gathering data
  2. Gather sources: code, git history, docs, issues, external references
  3. Map dependencies and identify circular deps or god packages
  4. Analyze hotspots: high churn + high complexity = refactor candidates
  5. Triangulate findings across at least 3 independent sources
  6. Synthesize into structured document with evidence and recommendations

Anti-patterns

FAIL: Drawing conclusions from a single source

# BAD: trusting a single comment or doc
# docs say "this is the target service" — may be outdated

# GOOD: triangulate
# 1. Check actual imports in go.mod
# 2. Read handler entry points
# 3. Verify with git history ownership

FAIL: Confusing documentation with implementation reality

# BAD: trusting README over source code
# README says "supports async" — check actual code

# GOOD: verify assumptions
# grep -r "async\|goroutine\|channel" ./services/

FAIL: Relying on intuition instead of statistical data

# BAD: "I think services is the most complex module"
# no data to back it up

# GOOD: measure it
# gocyclo ./services/ && git log --numstat -- services/

Claim Verification and Fact-Check

Applies when a research question demands factual verification, not codebase exploration (closes the "no general web research" gap, master catalog #102):

  1. Extract claims: split the question into individual checkable claims
  2. Gather evidence: collect at least two independent sources per claim
  3. Structured verdicts: mark each claim VERIFIED, PARTIALLY VERIFIED, or UNVERIFIED
  4. Transparent report: list every source with its access date and any conflict between sources

Rules:

  • A claim stays UNVERIFIED when sources conflict or a source cannot be located
  • Rank sources: primary documentation and vendor docs above aggregators
  • Never fabricate a citation; an unverifiable claim is reported as UNVERIFIED, not silently dropped

References

Verification Checklist

  • [ ] Research question defined explicitly before gathering data
  • [ ] Findings triangulated across at least 3 independent sources
  • [ ] Code behavior verified by reading actual source (not trusting docs/comments alone)
  • [ ] Statistical evidence gathered (grep counts, git stats) — not intuition
  • [ ] Circular dependencies and god packages identified in dependency map
  • [ ] Hotspot analysis run: high churn + high complexity files identified
  • [ ] Structured findings document produced with evidence and recommendations

Troubleshooting

Symptom Likely cause Fix
Conclusion contradicts actual code Relied on documentation instead of reading source Re-read the actual source files; doc is always secondary to code
Multiple false hotspots identified Git log includes auto-generated or vendored files Exclude generated code and vendor dirs from git log analysis
Dependency graph shows no circular deps Static grep misses dynamic imports or runtime resolution Use AST-level analysis tool (e.g., go tool deps) instead of grep for Go modules
Git log hotspot analysis skews toward recent commits (known issue: recency bias in git mining) Recent history weighted equally with all-time history Use time-windowed analysis (last 3 months, last year) instead of full git log; compare delta

04 同仓库更多 Skills

ronsilver
ronsilver/agent-covenant

web-browsing-agent-expert

Web browsing for AI agents: driving a headless browser (Playwright, Puppeteer) from agent tooling, navigation and page-state grounding, DOM extraction and structured data capture, form interaction, session and cookie management, anti-bot mitigation awareness, and safe browsing rules (no PII exfiltration, respect robots and terms). Use when building a browsing tool or MCP server for an agent, teaching an agent to navigate and read web pages, extracting structured content from dynamic sites, or handling login walls and pagination in agent workflows. Trigger: web browsing agent, headless browser, Playwright MCP, Puppeteer, browser automation for agents, DOM extraction, page navigation, session management. Do NOT trigger for: end-to-end UI testing of an application (use playwright-expert); writing standalone scraping scripts for data pipelines (use python-expert); fetching a single public URL (use the fetch tool).

★ 1
ronsilver
ronsilver/agent-covenant

vector-databases

Design and operate vector databases for cloud-native AI features. Use when selecting between pgvector, Pinecone, or Weaviate for AI context layer or integration-hub; designing embedding schemas and index parameters; implementing ANN search with metadata filtering; managing embedding model versions; optimizing query latency; or debugging low retrieval quality. Pairs with rag-architecture for pipeline design and postgres-database-expert for pgvector specifics. Trigger: vector database, pgvector, Pinecone, Weaviate, embedding, ANN search, HNSW, cosine similarity. Do NOT trigger for: relational SQL optimization, standard PostgreSQL schema design, Redis caching.

★ 1
ronsilver
ronsilver/agent-covenant

typescript-expert

Full-stack TypeScript stack for modern projects: frontend SSR/CSR with Next.js 14 App Router and React, backend APIs with Node.js (Express/Fastify), state management with Zustand/Redux Toolkit, unit and integration testing with Vitest/Jest + React Testing Library + MSW, and static analysis with ESLint/Prettier/tsc. Use when building React components or hooks, implementing Next.js App Router or Server Components, writing Node.js REST API handlers, implementing middleware (auth, rate-limit, logging), managing client state (Zustand/RTK), writing frontend/backend tests, or running TypeScript linting/type checks. Trigger: TypeScript, Next.js, React, Zustand, Node.js, Express, Fastify, MSW, Vitest. Do NOT trigger for: Python backend development, Go microservices, iOS/mobile development.

★ 1
ronsilver
ronsilver/agent-covenant

tool-usage

Guide correct tool selection, design, and orchestration for AI agents. Use when choosing between dedicated vs Bash tools, designing MCP tool interfaces, naming tool parameters, handling tool response limits, orchestrating parallel vs sequential calls, evaluating tool accuracy, applying ACI design principles, selecting workflow patterns, or reading/filtering/transforming/generating structured data (JSON, YAML, CSV, TOML, XML). Trigger: tool selection, MCP tool design, orchestration, ACI, parallel execution, composite tool, structured data, jq, yq, dasel, mlr, csvkit. Do NOT trigger for: writing application business logic, domain-specific development (route to domain skill), database migrations.

★ 1
ronsilver
ronsilver/agent-covenant

token-efficiency

Enforce token-efficient output, compression, caching, and model routing. Use when calibrating response verbosity, applying compression strategies to logs or RAG chunks, routing tasks to the right model tier, setting thinking budgets, enforcing word limits, compressing context before reinitiation, applying KV-cache ordering, masking tool output observations, or applying clarification-first protocol before irreversible actions. Trigger: token efficiency, compression, model routing, thinking budget, KV-cache, clarification protocol. Do NOT trigger for: non-agent tooling, CI/CD pipeline scripting, infrastructure provisioning.

★ 1
ronsilver
ronsilver/agent-covenant

time-series-db

Time-series database patterns for cloud-native metrics and analytics: TimescaleDB, InfluxDB, and Amazon Timestream selection; continuous aggregates, retention policies, downsampling, and integration with Prometheus/Grafana. Use when storing business metrics over time, building custom business dashboards, designing high-frequency event storage, or querying time-bucketed aggregations. Trigger: time-series, TimescaleDB, InfluxDB, Prometheus, Grafana, hypertable, continuous aggregate, retention policy. Do NOT trigger for: relational PostgreSQL schema design, NoSQL document stores, Kafka event streaming.

★ 1