菜单
Guided codebase exploration for understanding a repo's architecture, patterns, and domain language before contributing. Not issue-specific. builds general understanding. Use when exploring a new repo, wanting to understand how a project works, or preparing to become a regular contributor.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | oss-explore-repo |
| description | Guided codebase exploration for understanding a repo's architecture, patterns, and domain language before contributing. Not issue-specific. builds general understanding. Use when exploring a new repo, wanting to understand how a project works, or preparing to become a regular contributor. |
Explore a codebase the way experienced contributors do. by understanding the architecture, the patterns, and the domain language before touching anything.
Different from oss-prep-to-contribute (which is issue-specific and focused on one code path). This skill is for building broad understanding of a repo. Useful when a contributor wants to become a regular contributor rather than make a single drive-by PR. Also useful for GSoC candidates who need to demonstrate deep project understanding in their proposals.
gh CLI authenticatedBefore exploring anything, ask:
This shapes the depth. A GSoC candidate needs deep understanding. Someone evaluating a library needs a quick architecture scan.
Start with what the project DOES, not what the code looks like. Read:
# Project identity
cat README.md
cat docs/index.md 2>/dev/null || cat docs/README.md 2>/dev/null
# What problem does it solve?
gh api repos/{owner}/{repo} --jq '{description, homepage, topics, language, stargazers_count, open_issues_count}'
The user should be able to explain what the project does to a non-technical person before reading a single source file.
Thinking gate:
"Explain what this project does in one sentence. Who uses it? What problem does it solve? Don't use the README's words. rephrase it as if you're explaining to a friend who doesn't code."
If the user can't do this clearly, they need to read more docs before touching code.
Use Explore agents to map:
# Directory layout
ls -la
ls src/ lib/ app/ 2>/dev/null
ls -la */
# Entry points
cat package.json 2>/dev/null | jq '.main, .bin, .scripts'
cat setup.py 2>/dev/null || cat pyproject.toml 2>/dev/null
cat Makefile 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -30
# Key abstractions
grep -rn "class \|interface \|trait \|type \|struct " src/ lib/ \
--include="*.ts" --include="*.py" --include="*.go" --include="*.rs" --include="*.java" | head -40
Present a structured architecture summary:
Every codebase has its own vocabulary. Find the terms that appear everywhere:
# Domain-specific terms in variable/function/class names
grep -rn "class \|def \|function \|fn \|func " src/ lib/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | \
grep -oP '(class|def|function|fn|func)\s+\w+' | sort | uniq -c | sort -rn | head -20
# Comments that define domain concepts
grep -rn "// \|# \|/// \|/\*\*" src/ lib/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | grep -i "represents\|defines\|a .* is\|means" | head -15
# Glossary in docs (if it exists)
find docs/ -name "*glossary*" -o -name "*terminology*" -o -name "*concepts*" 2>/dev/null
Present terms the contributor must understand to read the code fluently. Group by importance. which terms appear in nearly every file vs which are module-specific.
Thinking gate:
"Pick 3 domain terms from the list above. Define each in your own words. Then find one place in the codebase where each is used. (This checks whether you can read the code, not just the summary I gave you.)"
What patterns does this codebase follow? Investigate:
# Error handling approach
grep -rn "try\|catch\|except\|Error\|Result\|unwrap\|panic" src/ lib/ --include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | head -20
# Testing patterns
ls test/ tests/ __tests__/ spec/ 2>/dev/null
cat test/*.{ts,py,go,rs} 2>/dev/null | head -40
# How new features get added - look at recent PRs
gh pr list -R {owner}/{repo} --state merged --limit 5 \
--json title,changedFiles,additions,deletions \
--jq '.[] | {title, files: .changedFiles, adds: .additions, dels: .deletions}'
Identify:
Thinking gate:
"If you were adding a new feature to this repo, describe the steps. which files would you create, what patterns would you follow, where would you add tests? Don't worry about getting it right. I'll tell you what you missed."
Review the user's answer. Point out conventions they missed without giving the full answer.
What's actively being worked on?
# Recent merged PRs - what areas are changing?
gh pr list -R {owner}/{repo} --state merged --limit 10 \
--json title,mergedAt,changedFiles --jq '.[] | {title, merged: .mergedAt, files: .changedFiles}'
# Open issues with most activity
gh issue list -R {owner}/{repo} --state open --sort comments --limit 10 \
--json number,title,comments --jq '.[] | {number, title, comments}'
# Recent releases
gh release list -R {owner}/{repo} --limit 5
# Changelog
cat CHANGELOG.md 2>/dev/null | head -50
Present:
Based on the exploration, what does the contributor still not understand?
If the repo uses technologies the user isn't familiar with, suggest → oss-learn-stack.
The user writes their own architecture summary. Not a copy of the LLM's summary from step 3. Their own version in their own words.
Thinking gate:
"Write a 5-10 line summary of this repo's architecture. Include:
- What it does (one sentence)
- How it's structured (main modules and their roles)
- The main patterns (error handling, testing, config)
- One thing that surprised you
This is YOUR mental model. It doesn't need to be perfect. it needs to be yours."
Review their summary. Flag anything incorrect but don't rewrite it.
oss-find-issue: find an issue that matches your new understandingoss-find-real-issues: use your understanding to find real code problemsoss-learn-stack: learn unfamiliar technologies from the repo itselfoss-prep-to-contribute: once you have an issue, prepare specifically for itoss-prep-to-contribute. this is general exploration, not issue-specific preparationDebug CI failures in unfamiliar repo pipelines. Reads CI configs, fetches failure logs, classifies the failure type, and guides the user through diagnosing and fixing the issue. Use when CI fails on your PR in an OSS repo, when you don't understand a CI error, or when debugging GitHub Actions/CircleCI/other CI systems. Not for setting up CI from scratch — this is for debugging existing pipelines.
Evaluate whether an OSS repo is worth long-term investment before committing time. Assesses project health, governance, community, bus factor, and trajectory. Use when deciding whether to contribute to a specific repo, choosing between multiple repos, or evaluating a project's sustainability. Not for checking if a repo accepts contributions — use oss-find-issue for that.
Handle PR review feedback - understand reviewer comments, research their concerns, and help the user address them. The LLM explains what reviewers want and why; the user decides how to respond and writes the code. Use when you receive review comments on a submitted PR.
Review other contributors' PRs to learn the codebase and build maintainer trust. Guides structured diff reading, helps formulate review comments, and teaches how to distinguish blocking issues from nits. Use when you want to learn a codebase by reviewing PRs, build trust with maintainers before contributing code, or practice code review on OSS repos. Not for reviewing your own PR — use oss-submit-pr for that.
Plan and execute your second and third contributions to become a regular contributor. Covers relationship building, progressive complexity escalation, and community presence. Use when your first PR was merged and you want to keep contributing, when transitioning from one-off contributor to regular, or when planning a sustained OSS involvement. Not for your first contribution — use the oss-find-issue → oss-contribute chain for that.
Set up a complete development environment for an unfamiliar OSS repo. Handles dependency installation, building, running tests, and configuring dev tooling. Use when cloning a new OSS repo and setting up for development, when the repo's setup instructions don't work, or when you need to debug environment issues. Not for setting up your own project — this is for getting someone else's repo running.