Project Context Map
Keep one compact architectural map per project at
~/.local/share/ai-agent-config/contexts/<slug>.md so agents find where things
live without broad exploration. The map is a starting point; the code is
always the source of truth.
Always read and write the canonical path. If an older install still has a
~/.config/opencode/contexts/ symlink, treat it as a legacy mirror and ignore
it.
Consult (default when starting a task)
- Identify the project:
- Inside a git repo:
git rev-parse --show-toplevel, use its basename.
- Otherwise: use the current working directory basename.
- Slug = lowercase, non-alphanumeric →
- (e.g. Miau Social → miau-social).
- Check
~/.local/share/ai-agent-config/contexts/<slug>.md. If present, read it
and confirm its path: frontmatter matches the current repo (a same-named
project elsewhere is a different project).
- Use it as a map: where things live, what to reuse, which commands to verify.
Confirm against the code before relying on it.
- If the map contradicts the code or is stale, trust the code and offer to
refresh the map with this skill (or refresh it yourself when asked / write
access allows).
- No map exists? Continue normally. If the task needs broad exploration, note
that a context map would save future tokens and recommend this skill.
Write / update (when asked to create or refresh, or when dispatched as writer)
- Resolve project and target path as above;
mkdir -p ~/.local/share/ai-agent-config/contexts.
- If the file exists, read it first and update incrementally: keep sections
that are still accurate, rewrite only what changed, add new discoveries, bump
updated:. Recreate from scratch only after a major restructure.
- Map the codebase efficiently. Read
package.json/manifest scripts + deps,
README, entry points, and the dir tree. Prefer scout role workers (see the
dispatching-parallel-agents skill) to keep the main session lean.
- Write a COMPACT map (target 30-60 lines) with this structure:
---
project: <slug>
path: <absolute repo path>
updated: YYYY-MM-DD
---
# <Project name>
## Objetivo
1-2 sentences: what the project is for.
## Stack
Languages, frameworks, key libraries, one per line.
## Estrutura
Each main directory → one line: what lives there and where to look.
## Arquitetura
Patterns: layers/DDD, DI, data access, auth, state. Where flows enter and exit.
## Fluxos importantes
Named flows (auth, checkout, build...) → starting file(s) for each.
## Abstrações a reutilizar
Existing components/services/helpers to reuse — never reinvent.
## Convenções
Naming, styling, forms, API, git conventions that differ from defaults.
## Comandos
test / lint / typecheck / dev / build / db.
## Dependências-chave
Only deps whose role matters: the "why", not the full list.
## Gotchas / não-óbvio
Things that cost exploration to discover: breaking framework versions, invariants, traps.
- Rules:
- Map, not dump: file paths + one-line purpose. No large code excerpts, no full configs.
- Facts only, sourced from the code — never invent.
- Keep it useful at a glance; trim stale entries while updating.
- After writing, report the file path and a 2-3 line summary of what changed.
1---2name: context3description: Use when starting work in a project before broad codebase exploration to check the project context map at ~/.local/share/ai-agent-config/contexts/<slug>.md, or when asked to create/update/refresh that map with this skill4metadata:5 source: https://skillmd.com/skills/existencialistap/context6---78# Project Context Map910Keep one compact architectural map per project at11`~/.local/share/ai-agent-config/contexts/<slug>.md` so agents find where things12live without broad exploration. The map is a starting point; **the code is13always the source of truth.**1415Always read and write the canonical path. If an older install still has a16`~/.config/opencode/contexts/` symlink, treat it as a legacy mirror and ignore17it.1819## Consult (default when starting a task)20211. Identify the project:22 - Inside a git repo: `git rev-parse --show-toplevel`, use its basename.23 - Otherwise: use the current working directory basename.24 - Slug = lowercase, non-alphanumeric → `-` (e.g. `Miau Social` → `miau-social`).252. Check `~/.local/share/ai-agent-config/contexts/<slug>.md`. If present, read it26 and confirm its `path:` frontmatter matches the current repo (a same-named27 project elsewhere is a different project).283. Use it as a map: where things live, what to reuse, which commands to verify.29 Confirm against the code before relying on it.304. If the map contradicts the code or is stale, **trust the code** and offer to31 refresh the map with this skill (or refresh it yourself when asked / write32 access allows).335. No map exists? Continue normally. If the task needs broad exploration, note34 that a context map would save future tokens and recommend this skill.3536## Write / update (when asked to create or refresh, or when dispatched as writer)37381. Resolve project and target path as above;39 `mkdir -p ~/.local/share/ai-agent-config/contexts`.402. If the file exists, **read it first and update incrementally**: keep sections41 that are still accurate, rewrite only what changed, add new discoveries, bump42 `updated:`. Recreate from scratch only after a major restructure.433. Map the codebase efficiently. Read `package.json`/manifest scripts + deps,44 README, entry points, and the dir tree. Prefer scout role workers (see the45 `dispatching-parallel-agents` skill) to keep the main session lean.464. Write a COMPACT map (target 30-60 lines) with this structure:4748```markdown49---50project: <slug>51path: <absolute repo path>52updated: YYYY-MM-DD53---5455# <Project name>5657## Objetivo581-2 sentences: what the project is for.5960## Stack61Languages, frameworks, key libraries, one per line.6263## Estrutura64Each main directory → one line: what lives there and where to look.6566## Arquitetura67Patterns: layers/DDD, DI, data access, auth, state. Where flows enter and exit.6869## Fluxos importantes70Named flows (auth, checkout, build...) → starting file(s) for each.7172## Abstrações a reutilizar73Existing components/services/helpers to reuse — never reinvent.7475## Convenções76Naming, styling, forms, API, git conventions that differ from defaults.7778## Comandos79test / lint / typecheck / dev / build / db.8081## Dependências-chave82Only deps whose role matters: the "why", not the full list.8384## Gotchas / não-óbvio85Things that cost exploration to discover: breaking framework versions, invariants, traps.86```87885. Rules:89 - **Map, not dump**: file paths + one-line purpose. No large code excerpts, no full configs.90 - Facts only, sourced from the code — never invent.91 - Keep it useful at a glance; trim stale entries while updating.926. After writing, report the file path and a 2-3 line summary of what changed.