What does this skill do, and when should you use it?
orient is a standalone skill inside the learning-opportunities repository, authored by Dr. Michael Mullarkey. It reads a repo's README, directory tree, language manifests, entry points, tests, and recent git history, then writes a structured orientation.md containing a one-line purpose, key files, core concepts, gotchas, and exactly two orientation exercises. Its exploration methodology is grounded in program-comprehension research including Spinellis's Code Reading and Hermans's The Programmer's Brain. The output is written at project level so it can be committed to version control and shared with teammates. A showboat mode uses Simon Willison's showboat CLI to produce a linear code walkthrough with numbered code listings.
At runtime it: detects the repo's primary languages via 10 manifest types (pyproject.toml, package., go.mod, etc.) and reads each detected manifest in full; explores the repo in the order README/docs, directory tree (find -maxdepth 3), language-specific entry points, 2-3 integration-oriented test files, 5-8 core modules, and git log churn analysis; then synthesizes orientation.md from a fixed template and writes it to .claude/skills/learning-opportunities/resources/ or .codex/skills/learning-opportunities/resources/ (creating only that file, leaving existing directory contents untouched). It finishes by telling the user where the file was written, how many key files and concepts were found, and to invoke /learning-opportunities orient for the lessons. With the showboat argument it instead builds a linear walkthrough (title, TOC, narrative sections, code-listings appendix via uvx showboat init/note/exec/verify), aborting with install guidance if uv is missing.
- A developer joining a team who wants to understand an unfamiliar codebase's structure in days, not weeks
- A maintainer inheriting someone else's project who needs a guide to key files and high-churn hotspots
- An agentic-coding user switching among multiple unfamiliar languages who wants a systematic mental model of each project
- Team onboarding: generated orientation.md files can be committed and reused by future members
- Educational contexts needing a directed path of 'open this file, then answer this synthesis question' exercises
How do you install this skill?
- Showboat mode fetches and executes a third-party CLI (showboat) via uvx from the network; confirm this external dependency and network behavior is permitted in your environment before use.
- The skill targets Claude Code / Codex platforms; compatibility with other environments is unverified. For mainland-China users, uvx fetching external tools may face network reachability issues.
- orientation.md is written into project-level .claude or .codex directories as a new untracked file; review content before committing.
- Static review only, nothing was executed; actual output quality and showboat command runnability are unverified — confidence is low.
- Shell / CLI
- Local filesystem
uv (required only for showboat mode, via uvx showboat)
Install as part of the learning-opportunities plugin marketplace. Claude Code: run /plugin marketplace add https://github.com/DrCatHicks/learning-opportunities.git, then /plugin install orient@learning-opportunities, then restart Claude Code. Codex: run codex plugin marketplace add https://github.com/DrCatHicks/learning-opportunities.git (the Codex marketplace lists orient). Source lives at orient/skills/orient/SKILL.md. The repo does not document manual copy-installation steps.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/DrCatHicks/learning-opportunities.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/orient/skills/orient" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
From the repo you want to learn: run /orient for the default mode, or /orient showboat for the walkthrough mode (requires uv installed). Then invoke /learning-opportunities orient to be offered two orientation lessons. Re-run orient at any time to regenerate as the codebase evolves.
What are this skill's strengths and limitations?
- Exploration steps cite concrete academic sources (Spinellis, Hermans, Storey et al.) rather than generic 'read the code' advice
- Exercise design principles are explicit: read a specific short artifact first, then synthesize — never predict unread content
- Output is project-level, version-controllable, shareable, and collision-free across projects
- Write strategy is safe: only orientation.md is written; existing directory contents are left untouched
- showboat mode produces a formal walkthrough with anchored listings and self-verifies via showboat verify
- External dependency: showboat mode hard-requires uv and stops entirely without it
- Output quality depends entirely on the underlying model executing the exploration steps; no test suite validates results
- Frontmatter uses platform-specific extensions (disable-model-invocation, $ARGUMENTS, argument-hint) that need editing to port to other Agent Skills clients
- Full value requires the companion learning-opportunities skill; standalone it yields only a static document
- Language detection covers 10 manifest types with no documented fallback for other languages or unconventional repo layouts
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Orient — Repo Orientation Generator this page | 55 · Use with care | ★ 2.5k | 2mo ago | CC-BY-4.0 |
| Codebase Recon | 58 · Recommended | ★ 41 | 6mo ago | MIT |
| Codebase Onboarding Guide Generator ✓ Microsoft · Official | 48 · Use with care | ★ 2.7k | 3mo ago | MIT |
| Learning Opportunities | 59 · Recommended | ★ 2.5k | 2mo ago | CC-BY-4.0 |
| Wiki Codebase Researcher ✓ Microsoft · Official | 52 · Use with care | ★ 2.7k | 3mo ago | MIT |
It pairs with the sibling skill learning-opportunities (learning-science exercises offered after architectural work): orient generates the orientation doc, and learning-opportunities with the orient argument delivers the two lessons from it. The README also recommends the related DrCatHicks/learning-goal skill for learning goal-setting.
How did FollowSkills review this skill?
The skill writes only one orientation.md, checks the target directory first, and never overwrites existing files; the default path uses Read/Glob/Grep/Bash (read-only git/find) plus Write, broadly least-privilege. The showboat path fetches and executes a third-party CLI via uvx from the network — an external dependency and execution surface — without explicitly warning the user. No sensitive-data handling risks, but no rollback guidance. Deducted for: unconfirmed network fetch/execution of a third-party tool via uvx.
Instructions are internally consistent: clear argument branching, explicit failure message and stop when uv is missing in showboat mode, precise output template. However, this is a static review: no tests, no sample outputs, no guidance for abnormal inputs (missing README, non-standard layouts), and key paths are not verified. Scored below the 10 anchor per calibration.
Trigger conditions are explicit (direct invocation only; disable-model-invocation: true prevents false triggering); audience (developers new to a codebase) is clear; output format has an exact template. Deducted for: undeclared non-fit boundaries (huge monorepos, multi-root workspaces) and showboat's dependency on uvx fetching an external tool, a mainland-China reachability risk with no fallback.
CC-BY-4.0 license present, author attribution explicit (Dr. Michael Mullarkey), a dedicated bibliography file documents methodology, and docs are well layered (SKILL.md + bibliography) with a maintainer note. Deducted for: no version number, no changelog, no known-limitations section for the skill itself; update path only implicit in repo maintenance.
The core task (generate a structured orientation.md consumed by learning-opportunities) is fully described with a directly usable template, and good/bad exercise criteria reduce low-quality output risk. Deducted for: static review cannot verify actual output quality or the runnability of the showboat command sequence; marginal value lacks empirical evidence.
Methodology cites specific academic sources (Spinellis, Hermans, Storey et al.) with an auditable bibliography file; but there are no tests, no CI evidence, no third-party execution or sample outputs, and the claim that the methodology improves orientation is not reproduced. Capped conservatively at 4 under static calibration.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →