Pencel

Appearance

Writing Context Files ​

Context files are the durable knowledge layer for your workspace. They are markdown documents describing people, systems, policies, and domain terminology that agents need to do useful work. This guide walks you through creating one.

For the principles behind what makes a context file effective, see the Authoring Rubric and Writing Effective Context Files.

Step-by-step: Create a context file ​

1. Open the Knowledge view ​

Navigate to Knowledge in the left sidebar and select Context. You see existing context files and a New File button.

2. Click New File ​

This opens a blank file editor with a filename input.

3. Name the file for its topic ​

Use kebab-case, end with .md, and name the file after the single topic it covers.

Good:

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

Avoid:

  • notes.md, general-info.md, file2.md
  • Anything that mixes two topics (finance-and-hr.md)

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

4. Write the body ​

Start with an H1 title, then use H2 sections to organize content. Front-load the most-queried information — who owns what, deadlines, escalation paths — and put history and rationale below.

Good context files contain durable facts, not dated updates. Names. Titles. System names. Dollar thresholds. Deadlines. Escalation paths.

Weak body:

This document is about the finance team. The finance team is very important. Mimi does a lot of things including close and also ticket approval.

Strong body:

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. Blackline Ticket Approval
- 48-hour SLA on all tickets
- Write-offs >$10K require Controller approval
- Write-offs >$25K need detailed justification

5. Set the domain (optional) ​

Domains are tags like finance, engineering, sales, hr that help you organize files when you have many of them. Leave blank if the file doesn't clearly belong to a single domain.

6. Set the activation mode ​

Context files have three modes:

  • Always — injected on every agent task. Reserve this for foundational identity files the agent needs on every run.
  • 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. Useful for drafts or reference-only material.

WARNING

Do not default to Always for topic-specific files. Each always-active file consumes context on every run, whether the task is relevant or not. Let Pencel's semantic matching surface topic files at the right time.

7. Save ​

Click Save. The file is stored and, if activation is Always or When Relevant, it will be included in matching agent tasks immediately.

What context files are (and are not) good for ​

Good fits:

  • Role descriptions — who owns what
  • System overviews — enterprise systems, their purpose, the conventions for using them
  • Policy documents — thresholds, SLAs, escalation paths
  • Domain glossaries — the vocabulary used at your company
  • Process maps — the steps of a recurring workflow, at a high level

Bad fits:

  • Dated updates (use memory or chat instead)
  • One-off instructions (use a prompt or a guideline)
  • Raw data dumps (use artifacts instead)
  • Long rationale essays (put the decision in the file; put the reasoning in a comment or changelog)

Keep each file short ​

A healthy context file is under ~300 lines. Longer files get only partially read by agents and their most important content can get buried below the fold. If you're approaching the limit, consider splitting by subtopic.

How many context files do you need? ​

Start with the foundational ones: workspace overview, the key people and their roles, the most important policies. Add more as you notice agents asking for information you could have provided upfront.

If you have more than ~20 context files in a workspace, audit for overlap — files that cover the same topic will both surface when their keywords match, which wastes context tokens.

Next steps ​