> ## Documentation Index > Fetch the complete documentation index at: https://docs.runspark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Writing Effective Knowledge Files > A deep guide to creating knowledge files that make your agent smarter 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](/agent/knowledge) yet, start there for setup instructions. ## The Principles "Our standard markup is 35% on all custom fabrication" is more useful than "We have competitive pricing." Showing your agent how to calculate a quote with a worked example teaches it better than listing abstract formulas. A focused "Pricing Guide" is better than an "Everything Document." Your agent retrieves files by relevance — smaller, focused files get matched more accurately. 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: ```markdown theme={null} # 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:** ```markdown theme={null} # 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:** ```markdown theme={null} # 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. ``` ### Company Information Help your agent represent your business accurately. **What to include:** * Company overview and history (2–3 sentences, not a novel) * Products and services offered * Team members and their roles * Office locations and hours * Key policies (returns, cancellations, SLAs) ### FAQ Documents Turn your most common questions into a structured FAQ your agent can reference: ```markdown theme={null} # 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: ```markdown theme={null} # 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 **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. **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. **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." **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. **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: 1. **Company Overview** — the big picture (referenced for general questions) 2. **Product Guides** — one per product or service line (referenced for product questions) 3. **Process Playbooks** — step-by-step workflows (referenced when taking action) 4. **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: ```markdown theme={null} ## 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](/crm/custom-fields)), document them: ```markdown theme={null} ## 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: 1. Update the knowledge file 2. Tell your agent in chat: "I just updated the pricing guide — the Enterprise tier is now $3,500/month instead of $3,000" 3. 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