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

orient

Orient a developer to an unfamiliar codebase by systematically exploring its structure, purpose, features, conventions, and workflows. Produces a concise orientation document. Use when the user says "orient me", "what does this project do", "walk me through this codebase", "help me understand this repo", "onboard me", "give me the lay of the land", "codebase overview", or any variation of wanting to quickly understand a project they're new to.

jcottam · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jcottam/agent-resources --skill orient

技能说明


name: orient description: >- Orient a developer to an unfamiliar codebase by systematically exploring its structure, purpose, features, conventions, and workflows. Produces a concise orientation document. Use when the user says "orient me", "what does this project do", "walk me through this codebase", "help me understand this repo", "onboard me", "give me the lay of the land", "codebase overview", or any variation of wanting to quickly understand a project they're new to. license: MIT metadata: author: jcottam version: "1.0.0"

Orient

Systematically explore a codebase and produce a structured orientation that tells a developer everything they need to start working productively. Depth scales with project size — small projects get a tight summary, large projects get a layered map.

Phase 1 — Project Identity

Establish what the project is before reading any source code.

Read top-level files (in order of priority)

  1. README.md / README — stated purpose, setup instructions, feature list
  2. AGENTS.md — architecture boundaries, "always do / never do" rules
  3. .cursor/rules/ — workspace conventions for this project
  4. Manifest file — package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, composer.json, or equivalent
  5. CONTRIBUTING.md, ARCHITECTURE.md, docs/ index — if present

Extract

  • One-sentence purpose: What does this project do, for whom?
  • Domain: What problem space does it operate in?
  • Stage: Early build, growth, or mature/stable?
  • Key dependencies: Frameworks, databases, external services

If the README is absent or unhelpful, infer purpose from the manifest description field, directory names, and import patterns.

Phase 2 — Shape

Map the physical layout without reading file contents yet.

# Get directory tree (depth 2–3 depending on project size)
find . -type f | head -200
# or
tree -L 3 -I 'node_modules|.git|dist|build|__pycache__|venv|.venv|target'

Categorize top-level directories

RoleCommon namesWhat to look for
Sourcesrc/, lib/, app/, pkg/, internal/Production code
Teststest/, tests/, spec/, __tests__/Test suites
ConfigRoot dotfiles, config/, .github/Build/CI/lint config
Docsdocs/, doc/, wiki/Documentation
Infrainfra/, deploy/, terraform/, k8s/, docker/Deployment
Scriptsscripts/, bin/, tools/Automation helpers
Generateddist/, build/, out/, target/Build artifacts (skip)

Identify the tech stack

From manifest files and directory structure, determine:

  • Language(s) and version constraints
  • Framework(s) — web, CLI, library, monorepo tooling
  • Database / storage layer
  • Build system and package manager
  • CI/CD platform (from .github/workflows/, .gitlab-ci.yml, etc.)

Phase 3 — Architecture

Now read code — but strategically. The goal is to understand the skeleton, not every function.

Scaling strategy

Project sizeApproach
Small (≤20 files)Read every source file. Full picture is cheap.
Medium (21–100 files)Read entry points + 3–5 core modules. Skim the rest by name/export.
Large (>100 files)Read entry points, trace one request/command end-to-end, read the 5 highest-import-count modules.

Find entry points

Look for:

  • main.ts, index.ts, app.ts, server.ts — web/API entry
  • main.py, app.py, __main__.py, manage.py — Python entry
  • main.go, cmd/ — Go entry
  • src/main.rs, src/lib.rs — Rust entry
  • bin/ scripts, CLI definitions
  • package.json "main", "bin", "exports" fields
  • Framework-specific: pages/, app/ (Next.js), routes/ (Express/Rails)

Trace the skeleton

From entry points, follow the import graph to identify:

  • Core modules — where the main logic lives
  • Data layer — models, schemas, database access
  • API surface — routes, handlers, controllers, exported functions
  • Shared utilities — helpers used across modules
  • Configuration — how settings flow into the system

Read 3–5 pivotal files fully to understand the primary abstraction patterns.

Identify boundaries

  • Monorepo packages / workspaces
  • Service boundaries (if microservices)
  • Plugin / extension points
  • Public API vs internal implementation

Phase 4 — Features and Functionality

Shift from code structure to user/consumer perspective.

For applications (web, CLI, desktop)

Enumerate:

  • User-facing features (routes, pages, commands)
  • Authentication / authorization model
  • Data inputs and outputs
  • Background jobs, workers, scheduled tasks
  • External integrations (APIs, webhooks, third-party services)

For libraries / SDKs

Enumerate:

  • Public exports and their purpose
  • Primary use cases (from README examples or test files)
  • Extension points (plugins, middleware, hooks)
  • Versioning / compatibility guarantees

For infrastructure / tooling

Enumerate:

  • What it provisions or manages
  • Configuration surface (env vars, config files, CLI flags)
  • Operational commands (deploy, rollback, scale)

Phase 5 — Conventions and Patterns

Extract the implicit rules that make contributions consistent.

Look for

  • Naming: File naming (kebab, camel, pascal), variable/function style
  • Code organization: Feature-based vs layer-based, barrel exports
  • Error handling: Custom error types, Result patterns, try/catch strategy
  • Testing: Unit vs integration split, fixture patterns, mocking approach
  • State management: Where state lives, how it flows
  • Type patterns: Strict vs loose typing, shared type definitions
  • Logging / observability: Structured logging, tracing, metrics

Sources of truth (in priority order)

  1. AGENTS.md explicit rules
  2. .cursor/rules/ files
  3. Linter/formatter config (.eslintrc, prettier, ruff.toml, clippy)
阅读完整来源 ↗