Learn Stack
Don't learn a framework from docs alone. learn it from how THIS repo uses it. This skill finds the patterns, explains the concepts, and points to real examples in the codebase you're about to contribute to.
Purpose
oss-prep-to-contribute does a knowledge check for one issue. This skill is broader: when a repo uses tech you don't know (unfamiliar language, framework, testing tool, build system, architecture pattern), this skill teaches those concepts using the repo itself as the textbook. Faster than reading generic docs because every example is from the actual codebase you'll contribute to.
Prerequisites
- A repo cloned locally
- At least a basic understanding of the project (from
oss-explore-repo or your own exploration)
- An honest assessment of what you don't know
Process
1. Identify the stack
Inventory the technologies used:
# Dependencies
cat package.json 2>/dev/null | jq '.dependencies, .devDependencies' 2>/dev/null
(cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null) | head -40
cat go.mod 2>/dev/null | head -20
cat Cargo.toml 2>/dev/null | head -30
# Build and CI tools
ls .github/workflows/ 2>/dev/null
cat Makefile 2>/dev/null | head -20
# Testing
ls test/ tests/ __tests__/ spec/ 2>/dev/null
grep -l "jest\|pytest\|mocha\|vitest\|cargo test\|go test" * .* 2>/dev/null
# Linting and formatting
cat .eslintrc* .prettierrc* pyproject.toml tox.ini setup.cfg 2>/dev/null | head -30
Present the full stack categorized:
## Stack: {repo}
| Category | Technology |
|----------|-----------|
| Language | {e.g., TypeScript 5.x} |
| Framework | {e.g., Express.js} |
| Testing | {e.g., Vitest + Testing Library} |
| Build | {e.g., Vite} |
| CI | {e.g., GitHub Actions} |
| Linting | {e.g., ESLint + Prettier} |
| Database | {e.g., PostgreSQL via Prisma} |
| Other | {anything else notable} |
2. Find the user's gaps
Ask targeted questions:
"Here's the stack this repo uses. For each technology, tell me your comfort level:
- Comfortable: used it in a project
- Familiar: read about it, haven't used it
- Unknown: never used it or only vaguely know what it is
Be honest. I'll focus teaching on the gaps. No judgment."
Process one gap at a time, starting with the most critical for the contribution they plan to make.
3. Teach from the codebase
For each identified gap, find real examples in this repo. Do NOT teach from generic docs.
# Find usage of the technology in the codebase
grep -rn "{framework_import_or_pattern}" src/ lib/ \
--include="*.ts" --include="*.py" --include="*.go" --include="*.rs" | head -20
# Find the simplest, clearest example
# (pick files that are short, well-named, and demonstrate the concept cleanly)
For each concept, present:
## {Technology}: {Concept Name}
**What it is**: {2-3 sentence explanation. just enough to read the code}
**How this repo uses it**:
- `src/handlers/auth.ts:15-30`: {what this example demonstrates}
- `src/middleware/validate.ts:8-22`: {what this example demonstrates}
**Walk-through** of `src/handlers/auth.ts:15-30`:
{line-by-line explanation of the key lines. not every line, just the ones that matter}
**Learn more**: {one link to official docs for this specific concept. not the homepage, the specific page}
Rules:
- Every example comes from THIS repo, not generic tutorials
- Explain in 2-3 sentences, not paragraphs
- One external link per concept (the specific doc page, not the homepage)
- Walk through the clearest example, skip the complex ones
4. Thinking gate: user reads the code
After explaining a concept:
"Now find one MORE example of {concept} in the codebase that I didn't show you.
Read it and tell me what it does.
(This checks whether you can recognize the pattern on your own, not just understand my explanation.
Hint: search for {relevant import or keyword} in the codebase.)"
If the user can find and explain an example, they understand the concept. Move to the next gap.
If the user can't find one or explains it wrong:
- Show one more example with a different angle
- Repeat the thinking gate
Don't move on until the user can recognize the pattern independently.
5. Connect to the contribution
Once gaps are filled, tie the learning to what the user needs to do:
"The issue you're working on touches {area} which uses {concept you just learned}.
Specifically, look at {file}:{line}: that's where your change will interact with {concept}.
Based on what you just learned, what do you think needs to change there?"
If the user doesn't have a specific issue yet, point to areas where the newly learned technology is most visible and suggest they explore those files on their own.
6. Build a reference sheet
The user creates their own quick-reference for while they code.
Thinking gate:
"Write a cheat sheet for yourself. 3-5 bullet points covering the key concepts you just learned, with file references for each.
This is your reference while you code. Write it in YOUR words, not mine.
Example format:
- {Concept}: {what it does}. See
{file}:{line} for an example"
Review their cheat sheet. Flag anything incorrect but don't rewrite it.
7. Verify readiness
Quick comprehension check:
"Without looking at your notes:
- What does
{key concept} do in this repo?
- If you saw
{pattern} in a file you haven't read yet, what would you expect it to do?
- Where would you look in the codebase for more examples of
{concept}?"
If the user can answer all three, they're ready to contribute. If not, revisit the relevant concept.
Related Skills
- Triggered from: ←
oss-prep-to-contribute: when knowledge check reveals unfamiliar technology
- Triggered from: ←
oss-explore-repo: when exploration reveals the user doesn't understand the stack
- Next step: →
oss-contribute: ready to work on the issue
- Pairs with:
oss-explore-repo (architecture understanding) + this skill (technology understanding) = full preparation
Common Rationalizations
| Shortcut | Why It Fails |
|---|
| "I'll read the official docs instead" | Docs teach the framework's happy path. This repo uses a subset of it, with local conventions layered on top. Code that is idiomatic for the docs and wrong for the repo is worse than code that is merely wrong, because it looks deliberate. |
| "I already know this framework" | Knowing the framework is not knowing how this repo uses it. The gap that costs you a review round is always the local convention, never the language. |
| "I'll learn it when I hit it" | You hit it halfway through the implementation, and the patch that comes out reads like it was written by someone guessing. Reviewers can tell. |
| "I found one example, that is the pattern" | One example might be the outlier nobody has cleaned up yet. Find a second before copying it. |
| "I'll just ask the LLM to explain the concept" | A general explanation is what the docs already gave you. The point of this skill is the explanation grounded in this codebase's own files. |
Red Flags
- User cannot find a second example of a concept unaided. the first one was not understood, only read
- The stack list has run past ten items. that is a repo tour, not a gap list, and none of it will stick
- User is reading framework tutorials in another tab instead of the repo's code
- The cheat sheet is copied from documentation rather than written from the repo's usage
- Every explanation ends with the user saying "makes sense" and asking nothing
Verification Checklist
Anti-patterns
- DO NOT teach from generic docs. every example must come from THIS repo's codebase
- DO NOT dump all concepts at once. teach one gap at a time, verify understanding, then move on
- DO NOT skip the "find another example" gate. recognition matters more than explanation
- DO NOT teach more than what's needed for the contribution. the goal is sufficiency, not mastery
- DO NOT replace official documentation. point to it for depth, don't reproduce it
- DO NOT assume the user knows prerequisite concepts. if they're unknown on React, don't assume they know JSX