Context Base — make every AI agent session start with project context

README.md

Context Base

Context Base helps a fresh AI-agent session understand a project before it starts making changes.

It reads the repository first, separates facts from guesses, and asks the user only about context the code cannot reveal: mission, priorities, decisions, and constraints.

Install

1. Download SKILL.md from this Gist.
2. Create a context-base folder inside your agent's skills directory.
3. Put SKILL.md inside that folder.
4. Restart the agent, then ask: Set up a context base for this project.

Common skill locations:

Claude Code: ~/.claude/skills/context-base/SKILL.md
Codex:       ~/.codex/skills/context-base/SKILL.md
Shared:      ~/.agents/skills/context-base/SKILL.md

What it creates

The skill inspects the project and builds only the context files it needs. It can record:

• confirmed mission and priorities;
• accepted decisions and hard constraints;
• a concise system map;
• verified workflows and conventions;
• important unknowns and conflicting evidence.

It does not invent product or architecture decisions. If the repository cannot answer something important, it asks the user or records it as unknown.

Included toolkit

The full lead-magnet download also includes 10 ready-to-copy Markdown templates for projects that need a faster starting point.

SKILL.md

name

context-base

description

Build, repair, or maintain a concise project context base that lets fresh AI-agent sessions understand a repository quickly and accurately. Use whenever the user asks for a context base, project memory, context-as-code, an agent briefing system, durable project knowledge, or better session-to-session continuity. Inspect the repository and its documentation before asking questions; separate verified facts, labeled inferences, and unknowns; ask the user only for missing mission, priorities, decisions, or constraints; and never invent product or architecture decisions.

Context Base

Create durable project context that helps a fresh agent start like an informed contributor. Treat context as maintained project infrastructure, not a large summary of everything in the repository.

Core standard

A useful context base is:

• Evidence-backed: claims point to code, configuration, tests, or existing documentation.
• Honest: facts, inferences, and unknowns are visibly different.
• Selective: it records intent, decisions, boundaries, and navigation that cannot be recovered cheaply from source code alone.
• Current: volatile information is dated and easy to revise.
• Non-duplicative: it links to authoritative sources instead of copying them.
• Safe: it never stores secrets, credentials, private logs, or production data.

Do not turn the context base into a second codebase, a speculative roadmap, or a transcript dump.

1. Establish scope

Infer the requested project and outcome from the conversation. If the user asks for a new context base, default to docs/context/ unless repository instructions or an existing convention specify another location. If a context system already exists, improve it in place rather than creating a competing one.

Before editing:

1. Find and read every AGENTS.md, CLAUDE.md, or equivalent instruction file that governs files you may touch.
2. Read relevant source-of-truth files in full.
3. Preserve unrelated work and follow the repository's own edit and validation rules.

2. Inspect before interviewing

Inspect the project deeply enough to answer discoverable questions yourself. Start broad, then follow the paths that define behavior.

Read, when present:

• root and package READMEs;
• manifests, lockfiles, workspace files, and build scripts;
• application entry points and top-level module boundaries;
• schemas, migrations, API contracts, and generated-code notices;
• tests, CI workflows, deployment configuration, and environment examples;
• docs/, ADRs, runbooks, changelogs, and existing plans;
• ownership and contribution instructions;
• recent version-control history only when it clarifies current intent.

Prefer fast repository search and targeted inspection over reading every generated or vendored file. Never read or copy secret values from .env files. Environment variable names may be recorded from safe examples or code references when useful.

3. Build an evidence ledger

Before drafting durable context, sort every material claim into one of three classes:

• Fact: directly supported by inspected evidence or an explicit user statement. Record the source path, document section, symbol, command output, or user confirmation.
• Inference: a plausible interpretation that is not explicitly established. Label it Inference, explain the evidence briefly, and do not turn it into a decision or requirement.
• Unknown: information that cannot be established safely. State what is missing and why it matters.

When sources disagree, do not silently choose one. Record the conflict, identify which source currently controls behavior, and leave intent unknown unless an ADR or user decision resolves it.

Use this practical evidence order:

1. current executable behavior, schemas, and tests for what the system does;
2. accepted ADRs and explicit user decisions for why and intended direction;
3. repository instructions for contribution and operating rules;
4. current operational docs and configuration;
5. READMEs, plans, comments, and history as supporting evidence.

This order is not absolute. A migration may prove current schema while an ADR still owns the intended design. Describe both when they differ.

4. Interview only for human-owned gaps

Finish repository inspection first. Then ask only when a missing answer would materially change the context base and belongs to one of these categories:

• Mission: who the project serves, the problem it exists to solve, and the intended outcome.
• Priorities: what matters now, ordering, deadlines, and what is explicitly not a priority.
• Decisions: unresolved product, architecture, policy, or tradeoff choices.
• Constraints: hard business, legal, security, cost, compatibility, staffing, or operational limits.

Do not ask the user to explain facts available in the repository. Do not ask for nice-to-have background. Group the smallest useful set of questions, explain the specific gap each resolves, and provide the evidence already found so the user can answer quickly.

If the user is unavailable, continue with verified facts. Put unresolved items in unknowns.md; do not fill the gaps with guesses. A context base with explicit unknowns is more trustworthy than a complete-looking fiction.

5. Choose the smallest useful document set

Use the templates in templates/ as starting points, not mandatory bureaucracy. Read templates/README.md before creating a new context base.

Always create or maintain a short entry point such as CONTEXT.md. Add other documents only when the project has durable information for them:

• mission-and-priorities.md for user-owned purpose and current focus;
• decisions.md for accepted decisions and supersession history;
• system-map.md for boundaries and navigation, not file-by-file summaries;
• conventions.md for explicit and strongly observed rules;
• workflows.md for verified commands and operating sequences;
• external-systems.md for integrations and ownership without secrets;
• unknowns.md for material gaps, conflicts, and labeled inferences;
• change-log.md for material context updates.

Keep authoritative artifacts where the repository already owns them. For example, link to an ADR rather than restating its full rationale, and link to a schema rather than duplicating its fields.

6. Write concise durable context

Write for both humans and agents. Use plain language, short sections, stable relative paths, and explicit ownership.

For each material statement:

• state only what helps future work;
• cite its source nearby;
• distinguish current behavior from intended behavior;
• include Last verified: YYYY-MM-DD for volatile operational facts;
• name an owner only when evidence identifies one;
• use Unknown instead of placeholders that look confirmed;
• remove duplicated explanation when a link to the authority is enough.

Never invent a mission, priority, deadline, owner, requirement, architecture choice, customer claim, or roadmap item. Recommendations must be labeled Recommendation and kept separate from accepted decisions.

Avoid brittle line-number citations in durable files. Prefer a file path plus a stable heading, symbol, target, or key. Line numbers are useful only in the immediate completion report.

7. Make context loadable

The entry point should let a fresh agent answer four questions quickly:

1. What is this project and what outcome does it serve?
2. What is true now, and where is the proof?
3. What matters now, and which decisions or constraints govern work?
4. Which document should be opened next for this task?

Keep the default briefing small. Use an index and task-based reading routes so an agent loads detailed documents only when relevant. If repository instructions support it, add a short pointer from the existing agent instruction file to the context entry point; do not duplicate the context there.

8. Validate

Before declaring completion:

1. Re-open every created or changed context file.
2. Confirm every fact has evidence and every inference is labeled.
3. Confirm unknowns were not silently converted into decisions.
4. Check relative links and referenced paths.
5. Search for accidental secrets, tokens, private data, and placeholder claims.
6. Run the repository's required documentation or project checks.
7. Review the diff and remove duplication, stale wording, and unrelated changes.

Report what was created, what was verified, which commands ran, and any human-owned unknowns that remain. Keep the report short.

Maintenance rules

• Update context in the same change when a governing decision, boundary, workflow, integration, or priority changes.
• Append or supersede decisions; do not rewrite history to make an old decision look as if it never existed.
• Date priorities and operational claims that can become stale.
• Resolve unknowns by moving confirmed information into the owning document and recording the resolution.
• Periodically delete redundant context. More files do not mean better context.

Anti-patterns

Do not:

• ask the user for architecture that the code already reveals;
• describe inferred behavior as a requirement;
• copy whole READMEs, schemas, tickets, or source files into Markdown;
• preserve temporary implementation plans as permanent truth;
• record secrets or sensitive customer data;
• create parallel sources of truth;
• hide contradictions between docs and code;
• claim the context base is complete when material unknowns remain.