Writing Effective Knowledge Files - Spark OS Documentation

Your agent is only as good as what you teach it. Knowledge files are the primary way you transfer your business expertise to your AI agent — and the quality of those files directly affects the quality of your agent’s work. This guide goes beyond the basics. If you haven’t read Knowledge Files yet, start there for setup instructions.

The Principles

Specific beats general

“Our standard markup is 35% on all custom fabrication” is more useful than “We have competitive pricing.”

Examples beat rules

Showing your agent how to calculate a quote with a worked example teaches it better than listing abstract formulas.

One file, one topic

A focused “Pricing Guide” is better than an “Everything Document.” Your agent retrieves files by relevance — smaller, focused files get matched more accurately.

Write for a smart new hire

If a competent person on their first week could follow your docs and do the job correctly, your agent probably can too.

File Structure That Works

A well-structured knowledge file follows a consistent pattern:

# Topic Name

Brief overview of what this document covers and when to reference it.

## Section 1

Details, rules, and specifics.

### Examples

Concrete worked examples showing how to apply the rules.

## Section 2

More details...

## Edge Cases & Exceptions

Anything that deviates from the standard rules.

## FAQ

Common questions about this topic and their answers.

Use Markdown formatting in your knowledge files — headings, lists, tables, and bold text. Your agent reads Markdown natively and uses the structure to find relevant sections quickly.

What to Write: File by File

Pricing Guide

This is usually the highest-impact knowledge file. Your agent will reference it for quotes, proposals, and pricing questions. What to include:

Base prices for each product/service
Tier breakdowns and volume discounts
Calculation rules with worked examples
Rounding rules, taxes, and fees
What’s included vs. what costs extra
Seasonal pricing or special rates

Example:

# Pricing Guide

## Standard Packages

| Package | Price | Includes |
|---------|-------|----------|
| Starter | $500/month | Up to 5 users, basic support |
| Professional | $1,200/month | Up to 25 users, priority support, API access |
| Enterprise | $3,000/month | Unlimited users, dedicated rep, custom integrations |

## Add-Ons

- Additional users beyond package limit: $25/user/month
- Premium support (24/7): $200/month
- Custom onboarding: $2,500 one-time

## Discounts

- Annual payment: 15% off monthly rate
- Non-profit organizations: 20% off any package
- Referral discount: $100 off first month for both parties

## How to Calculate a Quote

Example: A company wants Professional with 40 users, paid annually.

1. Base: $1,200/month (Professional)
2. Extra users: 40 - 25 = 15 extra × $25 = $375/month
3. Monthly total: $1,200 + $375 = $1,575
4. Annual discount (15%): $1,575 × 0.85 = $1,338.75/month
5. Annual total: $1,338.75 × 12 = **$16,065/year**

Always round final totals to the nearest dollar.

Process Playbooks

Document your workflows step by step. Your agent follows these like a checklist. Example:

# New Lead Processing

When a new lead comes in:

1. Check if the contact already exists in the CRM
   - If yes: update existing record, add note about new inquiry
   - If no: create new contact with all available info

2. Assess lead quality:
   - Has a business email (not gmail/yahoo) → Warm
   - Mentioned a specific product or need → Warm
   - Requested pricing or demo → Hot
   - Generic inquiry, personal email → Cool

3. Set the pipeline stage:
   - Hot leads → "Qualified"
   - Warm leads → "Contacted"  
   - Cool leads → "New Lead"

4. Create a follow-up task:
   - Hot leads: follow up within 2 hours
   - Warm leads: follow up within 24 hours
   - Cool leads: follow up within 3 business days

5. If the lead mentioned a specific product, note it on the contact 
   and reference our Pricing Guide for any quoted amounts.

FAQ Documents

Turn your most common questions into a structured FAQ your agent can reference:

# Customer FAQ

## Do you offer free trials?
Yes — 14-day free trial on all plans. No credit card required. 
Full access to all features during the trial.

## What's your cancellation policy?
Cancel anytime. Monthly plans stop at the end of the billing cycle. 
Annual plans can be cancelled with a prorated refund for unused months.

## Do you offer custom integrations?
Yes, on the Enterprise plan. Custom integrations typically take 
2-4 weeks and start at $5,000. Contact our team for a scoping call.

## What payment methods do you accept?
Credit card (Visa, Mastercard, Amex), ACH/bank transfer (annual 
plans only), and wire transfer for Enterprise accounts.

Email Templates

Give your agent examples of how you communicate so it can match your tone:

# Email Templates

## Initial Outreach (Warm Lead)

Subject: Quick question about [their need]

Hi [Name],

Thanks for reaching out about [specific thing they mentioned]. 
I'd love to learn more about what you're looking for.

Would you have 15 minutes this week for a quick call? I can walk 
you through how we typically help companies like yours with [topic].

Here's my calendar link if you'd like to pick a time: [link]

Best,
[Agent Name]

## Follow-Up (No Response)

Subject: Re: Quick question about [their need]

Hi [Name],

Just circling back on my note from [timeframe]. I know things 
get busy — wanted to make sure this didn't slip through the cracks.

If now's not the right time, no worries at all. Just let me know 
and I'll check back in a few months.

Best,
[Agent Name]

Common Mistakes

Files that are too broad

Problem: A single file called “Company Info” that contains pricing, processes, FAQs, policies, team info, and company history.Fix: Split it into focused files — “Pricing Guide”, “New Lead Process”, “Customer FAQ”, “Company Overview”. Your agent retrieves files by relevance, and smaller files get better matches.

Missing edge cases

Problem: Your pricing guide covers the standard packages but not what happens when someone wants to mix packages, use a promo code, or pay in a non-standard currency.Fix: Add an “Edge Cases” section. If your team encounters it, your agent will too.

Vague instructions

Problem: “Handle VIP clients with extra care.”Fix: Define what “extra care” means: “VIP clients (tagged ‘VIP’ in the CRM) get same-day response on all inquiries, a dedicated point of contact, and a 10% courtesy discount on any new purchase.”

Outdated information

Problem: Your pricing changed 3 months ago, but the knowledge file still shows old rates.Fix: Review knowledge files monthly. Set a recurring task or schedule to remind yourself. When you update pricing, update the file — changes take effect immediately.

No examples

Problem: A pricing formula without a worked calculation.Fix: Always include at least one example for any rule that requires math or judgment. “For groups over 50 people, apply a 10% discount” is good. Adding “Example: Group of 75 at

20/person =

1,500 × 0.9 = $1,350 total” is better.

Advanced Strategies

Layered Knowledge

Structure your knowledge so your agent can go from general to specific:

Company Overview — the big picture (referenced for general questions)
Product Guides — one per product or service line (referenced for product questions)
Process Playbooks — step-by-step workflows (referenced when taking action)
Templates — reusable text and formats (referenced when composing output)

This mirrors how a real employee learns: start with the big picture, then specialize.

Conditional Logic

When your processes have branches, write them explicitly:

## Handling Quote Requests

IF the request is for under $5,000:
  → Agent can quote directly using the pricing guide
  → Send the quote via email

IF the request is between $5,000 and $25,000:
  → Agent prepares a draft quote
  → Flags it for human review before sending
  → Creates a task assigned to the sales manager

IF the request is over $25,000:
  → Agent collects requirements and contact details
  → Creates a detailed task for the account executive
  → Does NOT send pricing — enterprise deals require a custom proposal

Teaching Your Agent About Custom Fields

If you use custom fields (see Custom Fields), document them:

## Our Custom Fields

- **Industry** (dropdown): Technology, Healthcare, Finance, 
  Retail, Manufacturing, Other
- **Company Size** (number): Number of employees
- **Contract Start** (date): When their contract began
- **Referral Source** (text): Who referred them

When creating a new contact, always try to populate Industry and 
Company Size from the information available. If the lead came from 
a referral, fill in Referral Source with the referring person's name.

Versioning Tips

Knowledge files update instantly — there’s no deploy or restart needed. But for significant changes:

Update the knowledge file
Tell your agent in chat: “I just updated the pricing guide — the Enterprise tier is now $3,500/month instead of$ 3,000”
This ensures the agent’s short-term memory reflects the change before it next reads the file

Your agent reads knowledge files on demand, not all at once. When you update a file, the new content is available immediately the next time the agent references that topic. You don’t need to restart anything.

Checklist: Is Your Knowledge File Ready?

✅ Focused on one topic
✅ Uses clear headings and structure
✅ Includes specific numbers, rules, and policies
✅ Has worked examples for calculations or complex rules
✅ Covers edge cases and exceptions
✅ Written clearly enough for a new employee to follow
✅ Up to date with current pricing, processes, and policies

​The Principles

Specific beats general

Examples beat rules

One file, one topic

Write for a smart new hire

​File Structure That Works

​What to Write: File by File

​Pricing Guide

​Process Playbooks

​Company Information

​FAQ Documents

​Email Templates

​Common Mistakes

​Advanced Strategies

​Layered Knowledge

​Conditional Logic

​Teaching Your Agent About Custom Fields

​Versioning Tips

​Checklist: Is Your Knowledge File Ready?

The Principles

File Structure That Works

What to Write: File by File

Pricing Guide

Process Playbooks

Company Information

FAQ Documents

Email Templates

Common Mistakes

Advanced Strategies

Layered Knowledge

Conditional Logic

Teaching Your Agent About Custom Fields

Versioning Tips

Checklist: Is Your Knowledge File Ready?