跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

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.

LanguageSignal files
Pythonpyproject.toml, setup.py, setup.cfg, Pipfile, requirements.txt
JavaScriptpackage.json (no tsconfig.json)
TypeScriptpackage.json + tsconfig.json
RDESCRIPTION, NAMESPACE, any *.Rproj
RubyGemfile, any *.gemspec
Gogo.mod
RustCargo.toml
C/C++CMakeLists.txt, configure.ac, root-level Makefile
Java/Kotlinpom.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 of pyproject.toml
  • JavaScript/TypeScript: main field in package.json, index.js, src/index.ts
  • Go: files in cmd/*/main.go or root main.go
  • Rust: src/main.rs or src/lib.rs
  • R: R/ directory, the DESCRIPTION file's Imports
  • Ruby: files in bin/, lib/<gem-name>.rb
  • C/C++: main.c, main.cpp, or the primary target in CMakeLists.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. 
阅读完整来源 ↗