skills/common/engineering/project-context-pack/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
project-context-pack	Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.	true

Project Context Pack

Create or refresh a bounded project memory file, then use it to navigate the codebase with discipline.

Output target

Default cache path: .agent/project-context.md at the project root.

If the user names another path, use that path. If writing into the repo is risky or unexpected, ask before writing. Never write secrets into the cache.

Procedure

1. Find the root. Prefer git rev-parse --show-toplevel; otherwise use pwd. Completion: you know the root and current relative working directory.
2. Inventory cheaply. Use fd and rg first; fall back to find and grep. Respect ignore files by default. Exclude .git, dependency directories, build outputs, caches, generated files, binaries, and large artifacts. Completion: you have a bounded file inventory and top-level tree without opening many files.
3. Classify the project. Detect language, framework, package manager, build/test tools, docs, agent guidance, and likely entry points from filenames and small config reads. Completion: the pack names the project type and the files that justify it.
4. Read selectively. Read only high-value files by default: README, agent guidance, package/build config, docs index, main entry points, and files directly relevant to the user's current request. Cap per-file and total content. Completion: every included file has a reason.
5. Index symbols before browsing. For code questions, prefer tree-sitter or LSP when available. Otherwise use rg patterns for definitions, exports, imports, routes, tests, commands, TODOs, and error strings. Completion: the pack has symbol/search notes before any broad source reading.
6. Write the memory file. Create or update the cache with the template below. Completion: the file exists and records when it was generated, commands/searches used, files inspected, and next navigation rules.
7. Use the cache. Before future exploration, read the cache first. If stale or insufficient, refresh the smallest relevant section instead of rebuilding everything. Completion: subsequent work cites the cache and avoids repeated file browsing.

Navigation discipline

• Do not wander file-by-file. Start with fd, rg, tree-sitter, LSP, or the cache.
• Track inspected files in the memory file.
• Prefer narrow searches over whole-file reads.
• Prefer symbol outlines and matching snippets over full content.
• Re-read a file only when it changed, the cache is stale, or the exact details are needed.
• Ask before full-content extraction, large scans, or including sensitive files such as .env, credentials, private keys, tokens, browser profiles, or personal data.

Useful command patterns

root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
cd "$root"

# Inventory
fd --type f --hidden --exclude .git 2>/dev/null || find . -type f -not -path './.git/*'
tree -a -I '.git|node_modules|dist|build|target|.venv|__pycache__|vendor|coverage' -L 3

# Project signals
fd '^(README|AGENTS|CLAUDE|GEMINI|package.json|pyproject.toml|Cargo.toml|go.mod|Makefile|justfile|docker-compose.yml)$'

# Search before reading
rg -n "TODO|FIXME|HACK|XXX"
rg -n "^(export |class |def |function |interface |type |trait |struct |enum )"
rg -n "main\(|if __name__ == .__main__.|export default|module.exports"

Memory file template

# Project Context Pack

Generated: <timestamp>
Root: <absolute root>
Working directory: <relative path>
Status: <fresh|partial|stale>

## Purpose
<What this repo appears to do.>

## Project type
<Languages/frameworks/package managers and evidence.>

## Structure
<Bounded tree or directory summary.>

## Important files
- <path> — <why it matters>

## Commands
- Build: <command or unknown>
- Test: <command or unknown>
- Lint/typecheck: <command or unknown>
- Run/dev: <command or unknown>

## Entry points
- <path or symbol> — <evidence>

## Search and symbol notes
<Useful rg/tree-sitter/LSP findings.>

## Files inspected
- <path> — <reason> — <freshness note>

## Exclusions
<Skipped directories, large files, generated files, secrets policy.>

## Navigation rules for future agents
<How to answer common questions in this repo without repeated browsing.>

## Refresh notes
<What to refresh next and what is likely stale.>