KNOWLEDGE MANAGEMENT FOR AGENTS

KNOWLEDGE BASES AND STRUCTURED PROJECT DOCUMENTS A knowledge base is an organized collection of information that an agent, and its human colleagues, can consult to do their work correctly. It might contain policies, product details, procedures, glossaries, past decisions, and frequently asked questions. You saw in Chapter 47 that a knowledge base is often searched using RAG. But a knowledge base is more than a pile of documents. Its value comes from being organized, accurate, and written to be useful. Structured project documents are a particularly powerful part of this. A structured project document is a single, deliberately written file that describes how a project works, using clear headings and short, specific statements, so that anyone starting work, human or agent, can read it first. Think of a project_conventions.md file, which might state the naming rules, the folder layout, the tools used, the style of writing expected, and the known pitfalls. (A file ending in md is written in a simple text format called Markdown, which is just plain text with light labeling.) If every agent that works on a project reads this file first, they all follow the same rules from the start. Without it, each agent must discover or guess the conventions independently, and different agents will guess differently, creating inconsistent and sometimes conflicting results. Guidelines for writing a good project document include the following. Be specific and concrete, such as "dates are written day-month-year," rather than vague, such as "use the right date format." Be concise, because the document will occupy precious context space every time it is loaded. Put the most important rules near the top. Explain the reason behind non-obvious rules, because an agent that understands why can apply the rule sensibly in new situations. Include examples of correct and incorrect output. Keep one source of truth, and avoid scattering the same rule across many files that can drift apart. We will see in Chapter 50 how this idea has become a widely used convention for coding agents. SKILLS: PACKAGED REUSABLE CAPABILITIES AND INSTRUCTIONS A skill is a packaged, reusable bundle of instructions, supporting materials, and sometimes small scripts that teaches an agent how to perform a particular kind of task reliably, and that can be loaded when needed. Imagine a recipe card for a particular dish. It lists the ingredients, the exact steps, the timing, and a photo of the finished dish. Anyone given the recipe card can produce the dish in a consistent way. A skill is a recipe card for an agent. For instance, a "generate_invoice" skill might bundle the following. The written instructions for creating an invoice. The required fields, such as customer name, date, line items, tax, and total. The formatting rules. One or two example invoices, so the agent can see what good output looks like. Perhaps a template file or a small checking script. Once packaged, any agent can be given this skill, instead of the team re-explaining invoice formatting from scratch in each prompt. The benefits are strong. Consistency: different runs and different agents produce the same shape of output. Reuse: you write the knowledge once and use it many times. Efficiency: a well-designed skill can be loaded only when needed. A common design is progressive disclosure, where the agent first sees only a short name and description of each available skill, and loads the full details only for the skill it decides to use. This keeps the context lean, a theme from Part Five. Maintainability: when the invoice rules change, you update one skill and every agent benefits. Several agent products now support skills as a concept, and this book's tool environment is one example, although the exact file layouts and features differ between products and change over time. So focus on the idea, and check current documentation for the product you use. Good skill design includes the following. A clear description of when the skill should and should not be used, so the agent picks it correctly. Step-by-step instructions that are specific, not vague. Complete required inputs and outputs, so nothing is left to guess. Examples, especially tricky edge cases. A way to check the result, such as a short checklist the agent runs before finishing. Also review a skill for gaps that cause inconsistent output. Typical gaps include missing field definitions, unclear handling of missing data, no example of the desired tone, and no instruction about what to do when the input is invalid. If two runs of an agent using your skill produce visibly different structures, that is a sign the skill leaves too much to chance. Finally, treat third-party skills with the same caution as any outside code or content. A skill is instructions plus possibly executable scripts, so a skill from an unknown source could contain harmful instructions. Review it before adopting it, as you learned in the supply-chain discussion in Chapter 39.