Agent-Skills.md

Agent Skills: Extern Researcher

|

UncategorizedID: malhashemi/dotfiles/extern-researcher

Repository

malhashemi/dotfiles
malhashemi
18

Install this agent skill to your local

pnpm dlx add-skill https://github.com/malhashemi/dotfiles/tree/HEAD/dot_config/opencode/skill/extern-researcher

Skill Files

Browse the full folder contents for extern-researcher.

Download Skill

Loading file tree…

dot_config/opencode/skill/extern-researcher/SKILL.md

Skill Metadata

Name
extern-researcher
Description
|

Extern Researcher

Overview

Enable agents to efficiently study external open-source repositories by leveraging existing research first, using temporary workspaces for clones, and persisting findings to the global thoughts system.

When to Use

  • When needing to study patterns or implementations from external repositories
  • When checking if a repository has already been researched
  • When cloning an external repo for temporary study
  • When persisting research findings about external code
  • When cleaning up temporary workspace after research is complete

Key Concepts

Research-Centric Model

The catalog tracks research studies, not cloned repositories. Clones are temporary workspaces; research is the persistent artifact.

Directory Structure

The catalog lives inside the org-global shared/ directory so thoughts-cli can scan it and it syncs across all projects via the org-global git repo.

{thoughtsHome}/{orgGlobal.path}/shared/extern/   # Persistent research storage (canonical)
├── catalog.md                                    # Global research catalog
└── repos/{org-repo}/                             # Research documents per repository

{any-project}/thoughts/global/org/shared/extern/  # Same location via project symlink
{any-project}/.extern/                            # Temporary workspace (disposable)
└── {org-repo}/                                   # Cloned repos for study

The script reads ~/.config/thoughts/config.json to resolve thoughtsHome and orgGlobal.path automatically. Default: ~/thoughts/global/shared/extern/.

Catalog Format

The catalog uses markdown with YAML frontmatter:

---
type: extern-research-catalog
version: 1.0
last_updated: YYYY-MM-DD
total_repos_studied: N
total_studies: N

repos:
  - name: "org/repo"
    url: "https://github.com/org/repo"
    first_studied: "YYYY-MM-DD"
    study_count: N
    topics: ["topic1", "topic2"]
---

Scripts

Execute via justfile or directly with uv:

Via Justfile (Recommended)

just -f {base_dir}/justfile <recipe> [args...]

| Recipe | Arguments | Description | |--------|-----------|-------------| | list | | List all research in catalog | | search | term | Search catalog by repo or topic | | stats | | Show catalog statistics | | add-study | repo url topic document context | Add a new study to catalog |

Direct Execution

uv run {base_dir}/scripts/catalog.py <command> [args...]

| Command | Arguments | Description | |---------|-----------|-------------| | list | | List all research studies | | search | <term> | Search by repo name or topic | | stats | | Show catalog statistics | | add-study | --repo --url --topic --document --context | Add new study |

Core Workflow

Phase 1: Discovery (ALWAYS FIRST)

Before cloning any repository:

  1. Read the global catalog: {thoughtsHome}/global/shared/extern/catalog.md
  2. Search for the repo by name, URL, or topic
  3. If found:
    • Read existing research documents
    • Evaluate: Is this sufficient for current needs?
    • If YES: Use existing research, skip cloning
    • If NO: Proceed to Phase 2, noting what gaps exist
  4. If not found: Proceed to Phase 2

Phase 2: Workspace Initialization

If cloning is needed:

  1. Check if .extern/ exists in current project
  2. If not, create it: 
    mkdir -p .extern
  3. MUST copy AGENTS.md template to workspace: 
    cp {base_dir}/assets/workspace-agents.md .extern/AGENTS.md
    This provides agent guidance for future sessions working in this directory.
  4. Ensure .gitignore includes .extern/

Phase 3: Clone Repository

  1. Parse the input (URL, clone command, org/repo format)
  2. Derive directory name: {org}-{repo} (lowercase, kebab-case)
    • https://github.com/facebook/react → facebook-react
    • https://github.com/vercel/next.js → vercel-next-js
  3. Clone with shallow depth (unless full history needed): 
    git clone --single-branch --depth 1 {url} .extern/{org-repo}/
  4. Verify success

Phase 4: Research

  1. Focus on the specific question/topic
  2. Use appropriate subagents:
    • codebase-pattern-finder - Find implementations, usage examples
    • codebase-analyzer - Deep dive on specific components
    • codebase-locator - Find files by purpose/feature
  3. Document findings with file:line references
  4. Note connections to current project needs

Phase 5: Persist Research

  1. Create research document:

    • Location: {thoughtsHome}/global/shared/extern/repos/{org-repo}/
    • Filename: {YYYY-MM-DD}_{topic-slug}.md
    • Use the research document template below

  2. MUST update global catalog using the script (not manual file edits):

    just -f {base_dir}/justfile add-study \
  "org/repo" \
  "https://github.com/org/repo" \
  "Topic studied" \
  "repos/org-repo/YYYY-MM-DD_topic.md" \
  "Why this was studied"

    The script ensures consistent catalog formatting and validates entries.

  3. Sync thoughts if configured:

    thoughts sync

Phase 6: Cleanup (Optional)

When workspace is no longer needed:

  1. Confirm with user before deletion
  2. Remove .extern/ directory: 
    rm -rf .extern/
  3. Research remains in {thoughtsHome}/global/shared/extern/

Research Document Template

When creating research documents, use this structure:

---
date: {ISO timestamp}
repo: "{org}/{repo}"
url: "{full URL}"
topic: "{research topic}"
context: "{why this was studied}"
project: "{project that prompted this}"
tags: [extern-research, {domain-tags}]
---

# {Topic}: {Repo Name}

## Research Question

{What we set out to learn}

## Key Findings

### Finding 1: {Title}

{Description with code examples and file:line references}

### Finding 2: {Title}

{...}

## Applicable Patterns

{How these findings could apply to our work}

## References

- `{file}:{line}` - {description}

Suitable Subagents

| Agent | Use Case | |-------|----------| | codebase-pattern-finder | Find implementations, usage examples | | codebase-analyzer | Deep dive on specific components | | codebase-locator | Find files by purpose/feature | | web-search-researcher | Additional context about the project |

Important Constraints

  1. ALWAYS check catalog first - Never clone without checking existing research
  2. Workspace is temporary - Do not store valuable data in .extern/
  3. Research is permanent - Always persist to {thoughtsHome}/global/shared/extern/
  4. Update catalog - Every study must update the global catalog
  5. Respect clone depth - Use shallow clones unless full history needed
  6. Use org-repo naming - Include organization to avoid conflicts

Error Handling

  • Catalog not found → Auto-created on first add-study at {thoughtsHome}/global/shared/extern/catalog.md
  • Clone fails → Check URL format, network, permissions; report to user
  • Research exists but stale → Proceed with new research, reference existing findings
  • Workspace already exists → Reuse existing .extern/, check if repo is already cloned