paper-repo

Paper Repo

Discover implementation repository for a paper.

Ownership

This skill owns:

• metadata.yaml → repo_search section
• repo/ → cloned repository (when confidence is high/medium)

This skill does not:

• Download PDF or normalize paper
• Generate reading notes
• Modify identity or bibliography sections

Workflow

Step 1: Extract clues from paper content (scripts)
      → PDF metadata URLs
      → paper.md code links + context
      → Output: candidate URLs with evidence

Step 2: Search GitHub if needed (web-kit)
      → ask-search "{title} site:github.com" -e google -n 10
      → ask-search "{method_name} github" -e google -n 10
      → Add search results to candidates

Step 3: Verify candidates (web-kit)
      → crwlr crawl -o md "{repo_url}"
      → Judge: official vs reimplementation, author match, code-paper alignment

Step 4: Select best candidate and clone (if confidence >= medium)
      → git clone {repo_url} repo/
      → Update cloned_to in metadata.yaml

Step 5: Write repo_search to metadata.yaml
      → selected: best candidate with confidence
      → candidates: all found with sources

Input

Read from:

• $PAPERS_DIR/{folder_slug}/metadata.yaml
  • bibliography.authors — for author verification
  • bibliography.venue — for context
  • identity.aliases.doi — for citation matching
• $PAPERS_DIR/{folder_slug}/paper/paper.pdf
• $PAPERS_DIR/{folder_slug}/paper/paper.md

Output

Write to metadata.yaml:

repo_search:
  selected:
    url: "https://github.com/owner/repo"
    confidence: "high"  # high / medium / low / none
    source: "paper_md"  # paper_pdf / paper_md / github_search
    evidence:
      - "README cites the paper DOI: 10.xxx"
      - "Author names match: Hongbin Pei"
    type: "official"    # official / community / reimplementation
    cloned_to: "repo/"  # filled after git clone
  candidates:
    - url: "https://github.com/owner/repo"
      source: "paper_md"
      confidence: "high"
      context: "Code availability section mentions this URL"
    - url: "https://github.com/other/repo"
      source: "github_search"
      confidence: "low"
      context: "Name similarity only"

Clone Policy

Auto-clone when:

• confidence is high or medium
• Repo URL is valid GitHub/GitLab URL

Do not clone when:

• confidence is low or none
• No valid repo found
• User passes --no-clone flag

# Clone command (use Bash tool, not PowerShell)
cd $PAPERS_DIR/{folder_slug}
git clone {repo_url} repo/

Windows / NTFS: Some repos contain paths with characters invalid on NTFS (e.g. : in timestamps). If git clone checkout fails with path errors: download the repo as a zip archive instead, do not extract it. Record in metadata.yaml:

cloned_to: "repo.zip"
clone_note: "Archive only — contains NTFS-incompatible paths"

After cloning, update cloned_to field in metadata.yaml.

Scripts

extract_urls_from_pdf.py

Extract URLs from PDF metadata and annotations.

uv run --script "${SKILL_DIR}/scripts/extract_urls_from_pdf.py" $PAPERS_DIR/{folder_slug}/paper/paper.pdf

Output: JSON list of URLs found in PDF with source annotation.

extract_code_links_from_md.py

Extract code-related links from paper.md with surrounding context.

uv run --script "${SKILL_DIR}/scripts/extract_code_links_from_md.py" $PAPERS_DIR/{folder_slug}/paper/paper.md

Output: JSON list of code links with context lines.

Verification Criteria

Criterion	How to check
DOI citation	README or repo description contains paper DOI
Author match	GitHub owner name matches one of bibliography.authors
Method name	Repo name contains the method name from title
Paper link	README links to arXiv/publisher URL from urls.canonical
Code alignment	Repo implements the core algorithm described in paper

Confidence Levels

Level	Criteria
high	DOI citation + author match + official implementation stated
medium	Repo matches method name + README mentions paper, but no author match
low	Only name similarity, no explicit paper connection
none	No candidate found or clearly unrelated

Search Strategy

From paper content (Step 1)

Priority order:

1. paper.md → Code availability section, footnote links
2. paper.pdf → PDF metadata URLs, annotation links

Paper often explicitly states: "Code is available at https://github.com/..."

From web search (Step 2)

When paper content has no explicit link:

# Search by paper title + github
ask-search "{paper_title} github" -e google -n 10

# Search by method name (if identifiable)
ask-search "{method_name} github" -e google -n 10

# Direct GitHub search via site:
ask-search "site:github.com {method_name}" -e google -n 10

If GitHub search yields no high-confidence result, try general search (code may be on author homepage, project page, or as ZIP download):

ask-search "{paper_title} code download" -e google -n 5
ask-search "{first_author} {method_name} code" -e google -n 5

Verify candidates (Step 3)

For each candidate URL:

${SKILL_DIR}/../web-kit/scripts/crwlr crawl -o md "{repo_url}"

Look for:

• README content citing the paper
• Author profiles matching paper authors
• Code structure matching paper methodology

Integration

This skill runs after paper-acquire.

Use paper-import for end-to-end workflow including repo discovery.

References

File	When to read
repo-verification.md	Need detailed verification criteria