skilld
All skills
oaustegard avatar

/orienting-codebases

@04bfd5b
by Oskar Austegardoaustegard/claude-skills150 stars
6

Interactive codebase orientation for a HUMAN who wants to learn the code. Runs the same tree-sitting + featuring pipeline as exploring-codebases but synthesizes it into guided exercises and an HTML teaching artifact rather than an analysis document. Use for "orient me to this repo", "teach me this codebase", "walk me through this code", "learning orientation", or when someone wants genuine comprehension rather than a task completed. The audience is the test: if nobody is being taught and the goal is to get work done, use exploring-codebases instead.

Ask your Agent

Use this Skill: https://skilld.dev/gh/oaustegard/claude-skills/orienting-codebases

This session only. Nothing lands on disk.

README.md

≈691 tokens on demand. Your agent reads this file only when SKILL.md points to it.

orienting-codebases

Interactive codebase orientation for a human learner. Companion to exploring-codebases: same structural pipeline (tree-sitting + featuring), but synthesizes into guided HTML exercises rather than an analysis dump for the agent.

Why this exists

exploring-codebases answers "what is this repo?" for Claude. This skill answers it for the person sitting at the keyboard.

The difference matters. Claude can ingest a gather.py dump and reason about it immediately. A human needs to actively engage — predict, synthesize, explain, get things wrong, correct — to build durable understanding. Passive reading of generated analysis creates fluency illusion: it feels understood but isn't retained. (Bjork & Bjork on desirable difficulties; Tankelevitch et al., CHI 2024, on the metacognitive demands of generative AI.)

Why HTML

HTML makes the hardest pedagogical enforcement structural rather than behavioral:

  • Pause protocol via <details> — answers are physically hidden until the user clicks to reveal. No LLM drift can expose them prematurely; the generation effect is enforced by the DOM, not by prompt discipline.
  • Code-in-context — the pipeline already has the source. treesit extracts specific functions with line ranges and the artifact shows them syntax-highlighted alongside the question. The user does the cognitive work; they don't waste orientation time on file navigation.
  • Standalone reuse — an orientation.html anyone on the team can open in a browser. No tooling, no live AI session required. Collapsible exercises, architecture context, progress tracking.

Pedagogical principles

Exercise design draws from established learning science:

  • Generation effect — producing answers builds stronger memory than reading them (Roediger & Karpicke, 2006).
  • Pre-testing — attempting before knowing primes encoding, even when the attempt is wrong (Giebl et al., 2021).
  • Desirable difficulty — effort during learning produces stronger retention (Bjork & Bjork, 2013).
  • Fluency illusion — easy processing ≠ durable knowledge; active engagement counters it (Soderstrom & Bjork, 2015).
  • Expertise reversal — worked examples help novices but hinder experts; fading scaffolding addresses the transition (Kalyuga, 2007).
  • Program comprehension — experts sample strategically, not exhaustively (Hermans 2021; Storey et al. 2006; Spinellis 2003).

Full reference: DrCatHicks/learning-opportunities PRINCIPLES.md.

Lineage

Pedagogical design adapted from DrCatHicks/learning-opportunities (orient skill + PRINCIPLES.md). Pipeline from exploring-codebases. Presentation via composing-html.

License: CC-BY-4.0.

Source: SKILL.md on GitHub

Third-party checks

1 warning9d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill facilitates interactive codebase orientation for users by generating guided HTML exercises. It uses standard tools to download repository content from GitHub, analyze its structure, and present relevant code snippets in a pedagogical format. The operations performed are consistent with its stated purpose and follow safe development practices.

  • Socket3mo

    No alerts

  • Snyk9d

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at 04bfd5b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month

Capability

Other metadata
metadata
{
  "version": "0.4.0",
  "license": "CC-BY-4.0",
  "lineage": "Pedagogical design adapted from DrCatHicks/learning-opportunities (orient skill + PRINCIPLES.md). Pipeline from exploring-codebases. Presentation via composing-html."
}

README badge

README badge for oaustegard/claude-skills/orienting-codebases