orient
Generates a repo-specific orientation.md resource for the learning-opportunities skill. Invoke directly when the user asks for repo orientation; do not trigger automatically.
DrCatHicks · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add DrCatHicks/learning-opportunities --skill orient技能说明
name: orient description: Generates a repo-specific orientation.md resource for the learning-opportunities skill. Invoke directly when the user asks for repo orientation; do not trigger automatically. argument-hint: "[showboat]" disable-model-invocation: true allowed-tools: Read, Glob, Grep, Bash, Write
Create Orientation
Purpose
Generate a repo-specific orientation.md file inside the learning-opportunities skill's resources/ directory. This file is used by that skill when invoked with the orient argument to run a structured learning exercise for someone new to the codebase.
Step 1: Find where to write orientation.md
Always write to the project level, regardless of where the learning-opportunities skill is installed.
When running in Codex, write to:
.codex/skills/learning-opportunities/resources/orientation.md
When running in Claude Code, write to:
.claude/skills/learning-opportunities/resources/orientation.md
Both paths are relative to the current working directory.
If the target directory does not exist, create it. If it already exists, leave it and any files inside it untouched — only write orientation.md.
This keeps orientation files co-located with the repo they describe — they can be committed to version control, shared with teammates, and never collide across projects.
Argument check
You were invoked with arguments: $ARGUMENTS
If the argument is showboat, skip to the Showboat Path section below.
Otherwise, continue with Steps 2–5 (the default path).
Step 2: Detect the repo's primary language(s)
Check for these manifest/config files at the project root and note all that exist. A repo may use multiple languages.
| Language | Signal files |
|---|---|
| Python | pyproject.toml, setup.py, setup.cfg, Pipfile, requirements.txt |
| JavaScript | package.json (no tsconfig.json) |
| TypeScript | package.json + tsconfig.json |
| R | DESCRIPTION, NAMESPACE, any *.Rproj |
| Ruby | Gemfile, any *.gemspec |
| Go | go.mod |
| Rust | Cargo.toml |
| C/C++ | CMakeLists.txt, configure.ac, root-level Makefile |
| Java/Kotlin | pom.xml, build.gradle, build.gradle.kts |
| C# | any *.csproj or *.sln |
Record all detected languages. For each detected language, read its primary manifest file in full — it contains declared purpose, dependencies, entry points, and scripts/commands that are essential for orientation.
Step 3: Explore the repo
Use the following sequence, drawn from research on expert program comprehension strategies. Experts read strategically and selectively, not exhaustively. The goal is a mental model of structure, not line-by-line understanding.
3a. README and top-level docs
Read README.md, README.rst, or README at the project root. Also check for a docs/ directory — read its index or table of contents if present. This gives the stated purpose and intended audience.
Source: Spinellis, "Code Reading: The Open Source Perspective" (2003) — start with the build system and README before reading any application code.
3b. Directory tree
Run find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' to get the top-level structure. Read the directory tree as an architectural table of contents — naming conventions (src/, lib/, tests/, cmd/, pkg/) reveal intent before any code is read.
Source: Spinellis (2003) — "directory tree as table of contents."
3c. Entry points
Identify and read the main entry points based on detected language:
- Python:
__main__.py,cli.py,main.py, or the[tool.poetry.scripts]/[project.scripts]section ofpyproject.toml - JavaScript/TypeScript:
mainfield inpackage.json,index.js,src/index.ts - Go: files in
cmd/*/main.goor rootmain.go - Rust:
src/main.rsorsrc/lib.rs - R:
R/directory, theDESCRIPTIONfile'sImports - Ruby: files in
bin/,lib/<gem-name>.rb - C/C++:
main.c,main.cpp, or the primary target inCMakeLists.txt
Source: Hermans, "The Programmer's Brain" (2021, Manning) — follow the entry point and call graph one level at a time.
3d. Test files
Read 2–3 test files, prioritizing integration or end-to-end tests over unit tests. Tests are executable specifications — reading test names and assertions is one of the fastest ways to understand what a module is meant to do.
Source: Storey et al., "How Software Developers Use Tools, Cognitive Strategies, and Representations to Navigate Code" (IEEE TSE, 2006) — use the test suite as a specification.
3e. Core modules
Identify the 5–8 most important source files based on what you have learned. Read their top-level structure (class/function names, imports, docstrings) without necessarily reading every implementation in full.
3f. Recent git history (if git is available)
Run git log --oneline -20 to see recent activity. Run git log --format="%f" | sort | uniq -c | sort -rn | head -10 to identify the most-edited files. High-churn files are usually the core of the system.
Source: Spolsky practitioner writing — "find the biggest, most-edited file; read git history to understand why code is the way it is."
Step 4: Synthesize and write orientation.md
Write the file to the path identified in Step 1. Use this exact structure:
# Repo Orientation: [repo name]
> Generated by orient. Re-run to update.
## One-line purpose
[Single sentence: what this repo does and why it exists.
阅读完整来源 ↗