The Authoring Rubric

Guidelines, skills, and context files are all prompt-injected text. Every character you write competes with the current task for space inside the agent's context window, and every character is read by an LLM that is already extremely capable. This short rubric is the single source of truth for writing all three. The per-entity guides ("Effective Guidelines", "Writing Skills", "Writing Context Files") apply these tenets to their specific field, but the principles below are the same everywhere.

If you only remember one sentence from this page: specific, actionable, and as short as it can be while still teaching the agent something it does not already know.

The ten tenets

1. Concise beats exhaustive

The agent already knows what a PDF is, what JSON is, and how to be polite. Only add information the LLM cannot infer on its own. A guideline that explains what SOX is, what SAP is, and then finally what the rule is has spent 80% of its token budget on background the agent already has.

Weak (spends tokens on background):

Single sign-on, often abbreviated as SSO, is a modern authentication pattern that allows users to log into multiple systems with one set of credentials. In our environment we use Okta. When provisioning SSO access, always…

Strong (gets to the point):

When provisioning Okta access, grant only the minimum group memberships the role card specifies. Require Controller approval for any group that grants SAP write permissions.

2. Specific and actionable, not aspirational

If a human reviewer cannot mechanically check whether the agent followed the rule, neither can the agent. "Be professional" and "be careful with data" are wishes, not rules.

Weak:

Be careful with customer data.

Strong:

When referencing customer data in outputs, include only the company name and deal stage. Never include personal email addresses, phone numbers, or contract values in anything leaving the CRM.

3. Match degree-of-freedom to task fragility

Use loose prose when many paths work; use exact steps and commands when one wrong move breaks things. Don't over-constrain creative work; don't under-constrain fragile work.

• High freedom: "Draft a reply that matches the customer's tone, acknowledges the specific issue they raised, and offers a concrete next step." (Many valid drafts.)
• Low freedom: "Run exactly python scripts/reconcile.py --quarter $Q --confirm. Do not add flags. Do not change the script name." (One correct invocation.)

4. Explain why alongside the rule

A one-line reason lets the agent handle the edge cases you didn't enumerate. Without the reason, the first surprise sends the agent into guessing mode.

Weak:

Always use Treasury-provided FX rates.

Strong:

Always use Treasury-provided FX rates for translation (EUR/USD, GBP/USD). Why: market rates and ERP-derived rates drift from Treasury's month-end rate and produce consolidation differences auditors cannot sign off on.

5. Consistent terminology

Pick one word — customer or client, user or account, close calendar or month-end schedule — and keep it everywhere. Inconsistency costs tokens, confuses semantic matching, and makes your guidelines contradict each other by accident.

6. No time-sensitive content in the main body

"After August 2025, use the new API" decays silently the moment it becomes untrue. Put dated exceptions in a clearly labeled Legacy or Deprecated section so you notice them and prune them later, instead of embedding them in rules that will read as live guidance three years from now.

7. Name for discovery, not for you

Titles and filenames feed semantic activation — the system reads them to decide whether to load your entry at all. sap-access-governance is found; important-rules-v2 is not. Use specific nouns drawn from the terminology you already use at work.

• Weak: general-notes.md, Rules (updated), Helper Skill 2
• Strong: finance-close-calendar.md, sap-access-sod-enforcement, analyzing-contract-renewals

8. Progressive disclosure via activation mode

Every entity you write has an activation mode. Use it intentionally — this is how Pencel keeps the context window healthy.

• Always — included on every run, for every task. Pay this cost only for identity and safety rails ("never expose credentials", "always cite sources"). A handful of these is healthy; twenty is not.
• When relevant — surfaced only when the current task semantically matches the entry. This is the default and should cover almost everything. If a rule only matters when the agent touches PRs, do not make it always-active.

If you are tempted to mark something Always because "it's important," ask: important on every task the agent performs, or important on tasks about this specific subject? Only the first qualifies.

9. Show a concrete example

One before/after pair teaches more than three paragraphs of description. Every skill with a style dimension, every guideline with a formatting requirement, and every context file with a non-obvious convention should include at least one example the agent can pattern-match against.

10. One rule per entry, one topic per file

If you find yourself writing "and also" or "additionally" between two different ideas, split the entry. Semantic matching gets sharper, you can tune activation per rule, and your future self can delete or edit one rule without accidentally removing another.

• Weak: a single guideline titled "Finance Rules" containing accrual policy, close-calendar deadlines, and PO approval thresholds.
• Strong: three guidelines — po-accrual-management, close-calendar-deadlines, po-approval-thresholds — each with its own activation mode and its own edit history.

Quick self-check before saving

1. Could a new hire read this and do the right thing without asking a follow-up question?
2. Is there any sentence the agent would know without me saying it? Delete it.
3. Have I explained the why for each non-obvious rule?
4. If this rule decays in a year, is the expiration in a labeled section or hidden in the main body?
5. Is the activation mode honest about when this really matters?
6. Did I use the same words for the same concepts throughout?
7. Is this one rule or several? If several, split now, not later.

Apply this to…

• Guidelines → "Effective Guidelines" and "Writing Guidelines"
• Skills → "Writing Skills" and "Writing Skills: Step-by-Step"
• Context files → "Writing Context Files" and "Writing Context Files: Step-by-Step"