Expertise File Design

Guide for designing YAML expertise files that serve as mental models for agent experts.

MANDATORY: Act-Learn-Reuse Context

Expertise files are mental models, NOT sources of truth. They:

• Accelerate agent execution by pre-loading domain knowledge

• Are maintained by self-improve prompts, not humans

• Validate against the actual codebase (source of truth)

• Have enforced line limits to protect context windows

When to Use

• Creating mental models for new domain-specific agents

• Defining expertise schema structures (YAML)

• Structuring knowledge for Act-Learn-Reuse workflows

• Reviewing or auditing existing expertise file designs

• Setting up line limits and section priorities

Expertise File Structure

Core Template

{domain}/expertise.yaml

Mental model for {domain} agent expert

Last updated: {timestamp}

Lines: {current}/{max}

overview: description: "Brief description of this domain" primary_technology: "Main tech/framework" architecture_pattern: "Key pattern used"

core_implementation: main_module: file: "path/to/main/file.ext" lines: approximate_line_count purpose: "What this module does" key_exports: - name: "FunctionOrClass" type: "function|class|constant" purpose: "Brief description"

supporting_modules: - file: "path/to/support.ext" purpose: "Supporting functionality"

schema_structure: # For database/API domains entities: entity_name: fields: - name: "field_name" type: "data_type" constraints: "nullable, unique, etc." relationships: - target: "other_entity" type: "one-to-many|many-to-many"

key_operations: operation_category: operation_name: function: "function_name" file: "path/to/file.ext" signature: "func(param: Type) -> ReturnType" logic: "Brief description of what it does" edge_cases: - "Important edge case 1" - "Important edge case 2"

patterns_and_conventions: naming: - "Convention description" error_handling: - "How errors are handled" data_flow: - "How data moves through system"

best_practices:

• "Practice 1: Explanation"
• "Practice 2: Explanation"

known_issues:

• issue: "Issue description" workaround: "How to handle it" status: "open|resolved|wontfix"

integration_points:

• system: "External system name" method: "How integration works" considerations: "Important notes"

testing_notes:

• "How to test this domain"
• "Key test scenarios"

Line Limits

Domain Complexity Max Lines Guidance

Small/Focused 300 Single module, simple operations

Medium 500-600 Multiple modules, moderate complexity

Large/Complex 800-1000 Full subsystem, many operations

Absolute Max 1000 Never exceed - split into sub-experts

Section Priority

When approaching line limits, prioritize sections in this order:

• core_implementation - Essential for navigation

• key_operations - Critical for task execution

• best_practices - Prevents mistakes

• known_issues - Avoids wasted effort

• patterns_and_conventions - Nice to have

• testing_notes - Can reference external docs

Domain-Specific Templates

Database Domain

overview: database_system: "PostgreSQL|MySQL|MongoDB|etc" orm_pattern: "Raw SQL|ORM name|Query builder" connection_strategy: "Pooling|Single|Per-request"

schema_structure: tables: table_name: purpose: "What this table stores" primary_key: "id (UUID|INT)" fields: [...] indexes: [...] foreign_keys: [...]

key_operations: crud: create: {function: "", file: "", logic: ""} read: {function: "", file: "", logic: ""} update: {function: "", file: "", logic: ""} delete: {function: "", file: "", logic: ""}

specialized: bulk_insert: {...} transaction_handling: {...}

API/Service Domain

overview: api_style: "REST|GraphQL|gRPC" auth_method: "JWT|OAuth|API Key" versioning: "URL|Header|None"

endpoints: resource_name: base_path: "/api/v1/resource" operations: list: {method: "GET", auth: "required", pagination: "cursor"} create: {method: "POST", auth: "required", validation: "..."}

request_response_patterns: success_format: {...} error_format: {...}

Frontend/UI Domain

overview: framework: "React|Vue|Angular|etc" state_management: "Redux|Zustand|Context|etc" styling: "CSS Modules|Tailwind|Styled Components"

component_hierarchy: pages: - name: "PageName" route: "/path" children: [...]

shared: - name: "ComponentName" purpose: "Reusable for X"

state_structure: stores: store_name: shape: {...} actions: [...]

Seeding Strategy

When creating a new expertise file:

• Start minimal - Begin with overview and core_implementation only

• Let agent discover - Run self-improve to populate

• Iterate - Run self-improve until stable (no changes)

• Review - Human validates accuracy

• Maintain - Self-improve after every ACT

Anti-Patterns

Pattern Problem Solution

Copy-pasting docs Duplicates source of truth Reference files, don't copy

Including code Bloats file, goes stale Reference by function name

No line limits Context window overflow Enforce max lines strictly

Manual updates Human time wasted Self-improve prompt only

Flat structure Hard to navigate Use nested YAML sections

Validation Checklist

Before considering an expertise file complete:

• Valid YAML syntax (no parse errors)

• Under line limit for domain complexity

• All file paths verified to exist

• All function names verified accurate

• Overview section complete

• Key operations documented

• Best practices included

• Known issues captured

Related Skills

• agent-expert-creation : Full agent expert workflow

• self-improve-prompt-design : Maintaining expertise accuracy

• meta-agentic-creation : Building experts that build experts

Last Updated: 2025-12-15

Version History

• v1.0.0 (2025-12-26): Initial release