Pencel

Appearance

Writing Effective Context Files ​

Context files are the durable knowledge base for your workspace — markdown documents that describe people, systems, policies, and domain terminology that agents need on matching tasks. Good context files are specific, short, and topic-scoped. Bad context files are rambling paragraphs of history, aspirations, and undated updates that age badly.

The principles here are the same ones in the Authoring Rubric. This page applies them specifically to context files.

Name the file for its topic ​

The filename drives both the UI and semantic retrieval. Use kebab-case, end with .md, and name it after the single topic the file covers.

Weak:

notes.md
general-info.md
file2.md
team-stuff.md

Strong:

finance-close-calendar.md
mimi-responsibilities.md
sap-role-card.md
customer-segmentation-tiers.md

One topic per file. If your draft drifts into a second topic, stop and create a second file.

Write durable facts, not dated updates ​

Context files are injected into agents on every matching task, possibly for months. Anything dated becomes a silent lie the moment it changes.

Weak:

Alice is temporarily covering for Bob while he's out. Last week we decided to use the new format. Starting next quarter, all reports will go through the new tool.

Strong:

Flash reports are distributed by Day 5 of close at 5:00 PM Pacific by the Accounting Manager. Format: 1-page executive summary with traffic-light status indicators (Green/Yellow/Red). Distribution list: Controller, CFO, VP Finance, IR team. CC FP&A. Marked CONFIDENTIAL.

If a fact genuinely has an expiration date, put it under a clearly labeled ## Legacy or ## Deprecated section so you notice it and prune it later.

Front-load the most-queried information ​

An agent reading a context file may only see the first few screens if the file is large. Put the most-queried information first. Who owns what. What the deadline is. What the escalation path looks like. Put history, rationale, and context below the load-bearing facts.

Use headings so agents can skim ​

Give every file an H1 title and logical H2 sections. The agent will use the headings to navigate, the same way a human would. Do not rely on order — rely on named anchors.

Good structure:

markdown
# Mimi Chen — Roles & Responsibilities

**Title:** Accounting Manager
**Reports to:** David Park (Controller)

## 1. Month-End Close
- Owns the close calendar (target: Day 6 hard close)
- Produces flash report by Day 5, 5pm PT

## 2. Ticket Approval
- 48-hour SLA on Blackline tickets
- Write-offs >$10K require Controller approval
...

Be specific — names, thresholds, systems, escalation paths ​

Specific facts beat aspirational prose every time.

Weak:

The finance team is very important to our company. We believe in accuracy and integrity in everything we do.

Strong:

Write-offs >$10K require Controller (David Park) approval. Amounts >$25K require detailed written justification including business impact and root cause. Use the Controller escalation channel in Slack (#finance-escalations).

Use consistent terminology ​

Pick one word per concept — customer or client, close calendar or month-end schedule, incident or outage — and use it everywhere. Inconsistency costs tokens and confuses semantic matching.

One topic per file ​

If you find yourself writing two headings that could live in separate files (finance policies and the org chart, for example), split the file. Semantic retrieval gets sharper, each file has a clearer activation signature, and you can edit one without touching the other.

Bad: finance.md containing close calendar, tax policies, SOX controls, and the org chart.

Good: finance-close-calendar.md, tax-filing-deadlines.md, sox-controls-catalog.md, finance-org-chart.md.

Activation mode: default to "when relevant" ​

Context files have three modes:

  • Always — included on every agent task. Reserve this for foundational identity files the agent must have on every run (a workspace overview, a company mission). Most workspaces need at most one or two of these.
  • When relevant — surfaced only when the current task matches the file's content. This is the right default for topic-specific files.
  • Never — saved but not injected. For drafts or reference-only material.

Do not mark topic-specific files as always. Pay the token cost only for files that genuinely apply to every task.

Quick checklist before saving ​

  • [ ] Filename is kebab-case, ends with .md, names a single topic.
  • [ ] The H1 title matches the filename's intent.
  • [ ] Most-queried information is in the first screen.
  • [ ] Every fact is durable (no "last week", no "starting next month").
  • [ ] Specific names, thresholds, and systems — no aspirational prose.
  • [ ] Consistent terminology throughout.
  • [ ] One topic per file — split if drifting into a second.
  • [ ] Activation mode is when relevant unless the file is foundational identity.