Effective Guidelines

Guidelines are the rules your agents follow on every task. They shape behavior, enforce standards, and prevent mistakes. A well-written guideline saves you from reviewing the same issue over and over. A vague one gets ignored.

INFO

The principles below are the same ones in the Authoring Rubric, which is the single source of truth across guidelines, skills, and context files. This page applies the rubric specifically to guidelines.

Write actionable rules, not vague principles

The most common mistake is writing guidelines that sound wise but give the agent nothing concrete to do. Compare:

Before (vague):

Be professional in all communications.

After (actionable):

When drafting emails, always include a clear subject line, open with the
recipient's name, and close with a specific next step or call to action.
Never use slang, emojis, or exclamation marks in external communications.

The first version is a suggestion. The second version is a rule the agent can actually follow.

Choose the right category

Guidelines are organized by category. Picking the right one helps Pencel apply them in the right context.

Category	Use for	Example
Safety	Preventing harmful or risky actions	"Never include customer Social Security numbers in any output."
Quality	Output standards and formatting rules	"All reports must include an executive summary of no more than 100 words."
Communication	Tone, voice, and style rules	"Use American English spelling. Write at an 8th-grade reading level."
Data handling	Rules about sensitive or regulated data	"Redact all personal email addresses before including data in reports."
Process	Workflow-specific requirements	"Always check for existing artifacts before creating a new one."

TIP

If a guideline does not fit neatly into one category, choose the one closest to the consequence of breaking the rule. A formatting rule that could leak sensitive data belongs in Data handling, not Quality.

Activation modes: always vs when_relevant

Every guideline has an activation mode that controls when it is included in the agent's context.

• Always: The guideline is included in every interaction, no matter what the agent is working on. Use this for rules that should never be broken — safety policies, data handling rules, and brand voice standards.
• When relevant: Pencel uses semantic matching to decide whether the guideline applies to the current task. Use this for situation-specific rules that only matter in certain contexts.

Always-active examples:

• "Never expose API keys, passwords, or credentials in any output."
• "All financial figures must include the currency symbol and two decimal places."
• "Do not make up data. If information is not available, say so."

When-relevant examples:

• "When writing customer emails, CC the account manager."
• "For quarterly reports, include a year-over-year comparison table."
• "When analyzing support tickets, categorize by severity (P1-P4)."

WARNING

Do not make everything "always active." Each always-active guideline uses tokens on every API call, even when it is irrelevant. This increases cost and can crowd out the actual task instructions. Reserve "always" for your 3-5 most critical rules. A healthy workspace typically has 3-5 always-active guidelines and up to 15-20 when-relevant ones. If you have more than 25 total, audit for overlap and consolidate.

Scope guidelines to the right workspace

Guidelines can apply to a specific workspace or across all workspaces. Use workspace-scoped guidelines for rules that only matter in a particular context.

• Global guidelines: Brand voice, security policies, data handling rules that apply everywhere.
• Workspace-scoped guidelines: Project-specific formatting, team preferences, domain-specific terminology.

For example, your marketing workspace might have a guideline about brand tone, while your finance workspace has rules about decimal precision. Neither needs to apply to the other.

Guidelines vs agent restrictions

Guidelines and agent restrictions both shape behavior, but they work at different levels:

	Guidelines	Restrictions
Scope	Workspace-wide (all agents)	Per-agent
Best for	Company policies, safety rules, brand standards	Role-specific limits for one agent
Example	"Never expose credentials in output."	"Do not modify existing artifacts."

Rule of thumb: If every agent in the workspace should follow the rule, make it a guideline. If only one agent needs it, use a restriction on that agent.

When guidelines conflict

If two guidelines give contradictory instructions — for example, "be concise" and "include detailed analysis with supporting data" — the agent sees both and must choose. This produces inconsistent results.

To prevent conflicts:

• Review existing guidelines before adding new ones.
• Use workspace scoping to keep unrelated rules separate.
• Consolidate overlapping guidelines: "Be concise, but include detailed data tables when analyzing financials" is better than two separate rules.

Concrete before/after examples by category

Safety

Before: "Be careful with sensitive data."

After: "Never include the following in any output: Social Security numbers, credit card numbers, bank account numbers, or login credentials. If source data contains these, replace them with [REDACTED]."

Quality

Before: "Make sure reports are good."

After: "Every report must include: (1) a title with the date, (2) an executive summary under 100 words, (3) at least one table or chart, and (4) a 'Next Steps' section with 2-5 action items."

Communication

Before: "Write clearly."

After: "Use short sentences (under 20 words). Use active voice. Avoid adverbs. Define any acronym on first use. Write at a level that a new hire with no domain expertise could understand."

Data handling

Before: "Handle data responsibly."

After: "When processing customer data: (1) never store raw customer emails in artifacts, (2) aggregate data to groups of 10+ before including in reports, (3) use customer IDs instead of names in internal analysis."

Process

Before: "Follow the process." After: "Before creating any new artifact, search the workspace for existing artifacts with a similar name. If one exists, update it instead of creating a duplicate."

Start with these 5 guidelines

If you are setting up a new workspace, start with these five always-active safety guidelines:

1. No fabrication. "Do not invent data, statistics, or facts. If you do not have the information, state that clearly."
2. No credential leaks. "Never include API keys, passwords, tokens, or credentials in any output."
3. Confirm before sending. "Never send emails, messages, or external communications without explicit user approval."
4. Cite sources. "When referencing specific data, always mention which workspace file, artifact, or source it came from."
5. Respect scope. "Only access data and tools that are relevant to the current task. Do not browse unrelated workspace files."

INFO

These five guidelines add minimal token overhead (under 200 tokens total) and prevent the most common issues new users encounter. You can refine and expand from here.

Quick checklist

Before saving a guideline, verify:

• [ ] Does it describe a specific, observable behavior (not a vague aspiration)?
• [ ] Is the activation mode correct (always vs when_relevant)?
• [ ] Is it scoped to the right workspace (or global)?
• [ ] Is it short enough to be useful? (Aim for 1-3 sentences.)
• [ ] Could a new team member read it and know exactly what to do?
• [ ] Does it conflict with any existing guideline?
• [ ] Have you run a test workflow to verify the agent follows it?