name: Knowledge Base Builder
slug: knowledge-base-builder
description: Build and maintain AI-accessible knowledge bases for projects
category: meta
complexity: complex
version: "1.0.0"
author: "ID8Labs"
triggers:
- "build knowledge base"
- "create knowledge base"
- "knowledge base builder"
- "organize knowledge"
- "structure knowledge"
tags:
- knowledge-management
- documentation
- memory

Knowledge Base Builder

The Knowledge Base Builder skill helps you create, structure, and maintain knowledge bases that AI agents can effectively query and utilize. It transforms scattered information—from project documentation to tribal knowledge—into organized, accessible knowledge that improves AI performance and team productivity.

This skill guides you through knowledge extraction, organization, structuring, and maintenance. It understands different knowledge formats (documentation, code comments, decision logs, schemas), helps you choose appropriate storage (markdown files, knowledge graphs, databases), and ensures knowledge remains current and useful.

Use this skill when starting new projects, onboarding AI to complex systems, preserving institutional knowledge, or improving AI agent effectiveness through better context.

Core Workflows

Workflow 1: Build Knowledge Base from Scratch

1. Define knowledge base purpose:
2. Who will use it? (AI agents, developers, both)
3. What problems does it solve?
4. What scope/boundaries?
5. Identify knowledge sources:
6. Existing documentation
7. Code repositories
8. Team conversations
9. Decision records
10. Tribal knowledge
11. Extract relevant information:
12. Key concepts and relationships
13. Architectural decisions
14. Domain terminology
15. Common patterns
16. Troubleshooting knowledge
17. Structure the knowledge:
18. Choose organization (hierarchical, graph, hybrid)
19. Define categories/taxonomies
20. Establish relationships
21. Create metadata schema
22. Format for consumption:
23. Markdown for documentation
24. Knowledge graph for relationships
25. Schema files for structure
26. Code comments for implementation
27. Populate the knowledge base:
28. Create initial content
29. Link related concepts
30. Add examples
31. Include references
32. Validate accessibility:
33. Can AI find information?
34. Is context sufficient?
35. Are relationships clear?
36. Establish maintenance process

Workflow 2: Extract Knowledge from Codebase

1. Analyze codebase structure:
2. Architecture patterns
3. Module organization
4. Key abstractions
5. Data flow
6. Identify extractable knowledge:
7. Design decisions
8. API contracts
9. Data models
10. Business logic
11. Edge cases
12. Generate documentation:
13. Architecture overview
14. Component descriptions
15. API reference
16. Data dictionary
17. Integration guides
18. Create knowledge graph:
19. Entities (modules, services, models)
20. Relationships (depends on, implements, extends)
21. Observations (purpose, constraints, patterns)
22. Link to code:
23. File paths for reference
24. Function signatures
25. Configuration locations
26. Maintain synchronization:
27. Update on code changes
28. Version knowledge with code
29. Automate where possible

Workflow 3: Organize Project Knowledge

1. Audit existing knowledge:
2. What documentation exists?
3. What's missing?
4. What's outdated?
5. What's scattered?
6. Define structure:
7. Documentation hierarchy
8. File organization
9. Naming conventions
10. Cross-referencing approach
11. Create core documents:
12. README.md (overview, getting started)
13. ARCHITECTURE.md (system design)
14. DECISIONS.md (ADRs)
15. PIPELINE_STATUS.md (project state)
16. CONTRIBUTING.md (development guide)
17. Establish conventions:
18. Document templates
19. Metadata standards
20. Update procedures
21. Review processes
22. Populate with content:
23. Migrate existing docs
24. Fill gaps with new content
25. Link related documents
26. Add navigation
27. Integrate with AI:
28. Add to context
29. Create knowledge graph entries
30. Enable discovery
31. Test accessibility

Workflow 4: Build Knowledge Graph

1. Identify entities:
2. What are the key concepts?
3. What needs to be remembered?
4. What has relationships?
5. Define entity types:
6. Project (repos, services, apps)
7. Component (modules, features, functions)
8. Person (team members, stakeholders)
9. Decision (architectural choices)
10. Process (workflows, procedures)
11. Resource (docs, tools, dependencies)
12. Extract observations:
13. Facts about each entity
14. Properties and attributes
15. Context and purpose
16. Status and state
17. Map relationships:
18. How entities connect
19. Relationship types
20. Directionality
21. Strength/importance
22. Store in knowledge graph:
23. Use Memory MCP
24. Create entities
25. Create relations
26. Add observations
27. Query to validate:
28. Can you find entities?
29. Do relationships make sense?
30. Is information complete?
31. Maintain over time:
32. Add new entities
33. Update observations
34. Add new relationships
35. Prune obsolete information

Workflow 5: Maintain Knowledge Base

1. Monitor knowledge health:
2. Usage frequency
3. Outdated content
4. Gaps in coverage
5. User feedback
6. Update regularly:
7. Reflect code changes
8. Document new decisions
9. Add new patterns
10. Remove deprecated info
11. Review periodically:
12. Quarterly knowledge audit
13. Validate accuracy
14. Check completeness
15. Improve clarity
16. Optimize for consumption:
17. Improve searchability
18. Add missing links
19. Consolidate redundancy
20. Enhance examples
21. Gather feedback:
22. What's confusing?
23. What's missing?
24. What's most useful?
25. Iterate on structure:
26. Reorganize if needed
27. Add new categories
28. Improve navigation
29. Refine metadata

Quick Reference

Best Practices

• Start with Purpose: Define what the knowledge base should accomplish
• Enable AI to understand codebase
• Help new developers onboard
• Preserve architectural decisions

• Document domain knowledge

• Structure for Discovery: Make information findable

• Clear hierarchy
• Consistent naming
• Comprehensive indexing
• Rich cross-linking

• Metadata tagging

• Write for AI and Humans: Both will consume this

• Clear, concise language
• Structured formats (tables, lists)
• Explicit relationships
• Contextual information

• Code examples

• Keep It Current: Stale knowledge is worse than no knowledge

• Update with code changes
• Review regularly
• Remove obsolete info

• Version alongside code

• Make It Accessible: Knowledge must be reachable

• Link from README
• Reference in code comments
• Add to AI context

• Create in knowledge graph

• Use Multiple Formats: Different knowledge needs different formats

• Markdown for prose documentation
• Knowledge graphs for relationships
• Schema files for structure
• Code comments for implementation details

• Diagrams for architecture

• Preserve Context: Don't just document "what", document "why"

• Why this architecture?
• Why not alternative approaches?
• What constraints influenced decisions?

• What trade-offs were made?

• Link Generously: Connect related concepts

• Cross-reference documents
• Link code to docs
• Connect related decisions
• Reference external resources

Knowledge Base Structure

Recommended File Organization

/docs
  /README.md                 # Project overview
  /ARCHITECTURE.md           # System design
  /DECISIONS.md              # ADRs (Architecture Decision Records)
  /PIPELINE_STATUS.md        # Current project state
  /CONTRIBUTING.md           # Development guide
  /API.md                    # API reference
  /DATABASE.md               # Schema documentation
  /DEPLOYMENT.md             # Deployment guide
  /TROUBLESHOOTING.md        # Common issues
  /guides/                   # How-to guides
    /getting-started.md
    /development-workflow.md
    /testing.md
  /reference/                # Technical reference
    /components.md
    /utilities.md
    /configurations.md
  /decisions/                # Detailed ADRs
    /001-framework-choice.md
    /002-state-management.md

Documentation Templates

ARCHITECTURE.md Template

# Architecture

## Overview
[High-level system description]

## System Components
- **Component 1**: [Purpose and responsibility]
- **Component 2**: [Purpose and responsibility]

## Data Flow
[How data moves through the system]

## Key Design Decisions
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Technology Stack
- Frontend: [Technologies]
- Backend: [Technologies]
- Database: [Technologies]
- Infrastructure: [Technologies]

## Integration Points
- [External service 1]: [How we integrate]
- [External service 2]: [How we integrate]

## Security Considerations
[Security architecture and patterns]

## Scalability & Performance
[How system scales, performance characteristics]

DECISIONS.md Template (ADR Log)

# Architecture Decision Records

## ADR-001: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: Accepted | Proposed | Deprecated

**Context**:
[What is the issue we're trying to solve?]

**Decision**:
[What we decided to do]

**Consequences**:
- Positive: [Benefits]
- Negative: [Trade-offs]
- Neutral: [Other impacts]

**Alternatives Considered**:
1. [Alternative 1]: [Why rejected]
2. [Alternative 2]: [Why rejected]

---

## ADR-002: [Next Decision]
[...]

Component Documentation Template

# [Component Name]

## Purpose
[What this component does and why it exists]

## Location
`/path/to/component`

## Dependencies
- [Dependency 1]: [Why needed]
- [Dependency 2]: [Why needed]

## API
### Functions
- `functionName(params)`: [Description]

### Types
\`\`\`typescript
interface ComponentProps {
  // ...
}
\`\`\`

## Usage
\`\`\`typescript
// Example usage
\`\`\`

## Related Components
- [Component A]: [Relationship]
- [Component B]: [Relationship]

## Known Issues
- [Issue 1]: [Workaround]

Knowledge Graph Patterns

Entity Types for Software Projects

Project
  - name
  - description
  - status (active, maintenance, deprecated)
  - tech_stack

Component
  - name
  - type (service, module, function)
  - location (file path)
  - purpose
  - status

Person
  - name
  - role
  - expertise_areas
  - current_focus

Decision
  - title
  - date
  - status
  - context
  - choice
  - rationale

Process
  - name
  - type (workflow, procedure, standard)
  - steps
  - triggers
  - outputs

Dependency
  - name
  - version
  - purpose
  - critical (boolean)

Relationship Types

Project --depends_on--> Dependency
Project --contains--> Component
Component --uses--> Component
Component --implements--> Decision
Person --owns--> Component
Person --made--> Decision
Decision --supersedes--> Decision
Component --documented_in--> Document
Process --governs--> Component

Example Knowledge Graph Creation

// Create entities
await memory.create_entities({
  entities: [
    {
      name: "id8labs-app",
      entityType: "Project",
      observations: [
        "Next.js 14+ application",
        "Uses Supabase for backend",
        "Deployed on Vercel",
        "Monorepo structure"
      ]
    },
    {
      name: "authentication-module",
      entityType: "Component",
      observations: [
        "Located in /src/features/auth",
        "Handles user authentication via Supabase Auth",
        "Supports magic link and OAuth",
        "Implements RLS policies"
      ]
    }
  ]
});

// Create relationships
await memory.create_relations({
  relations: [
    {
      from: "id8labs-app",
      to: "authentication-module",
      relationType: "contains"
    },
    {
      from: "authentication-module",
      to: "Supabase Auth",
      relationType: "uses"
    }
  ]
});

Knowledge Extraction Techniques

From Code

• Function/Class documentation: Purpose, parameters, returns
• Module organization: Structure and relationships
• Design patterns: Implementation approaches
• Error handling: Known failure modes
• Performance considerations: Optimization notes

From Conversations

• Decisions made: Choices and rationale
• Problems solved: Issues and solutions
• Lessons learned: What worked, what didn't
• Open questions: Unresolved issues
• Action items: Tasks and owners

From External Sources

• API documentation: Integration guides
• Research papers: Technical approaches
• Stack Overflow: Common solutions
• Blog posts: Best practices
• Conference talks: Industry patterns

Knowledge Quality Checklist

Good knowledge base entries should:

• [ ] Have clear, descriptive titles
• [ ] Explain the "why" not just the "what"
• [ ] Include concrete examples
• [ ] Link to related concepts
• [ ] Specify when created/updated
• [ ] Indicate status (current, deprecated)
• [ ] Use consistent formatting
• [ ] Be discoverable through search
• [ ] Provide sufficient context
• [ ] Reference original sources

Maintenance Schedule

Daily

• Document new decisions as they're made
• Update PIPELINE_STATUS.md with progress
• Add code comments for complex logic

Weekly

• Review open questions and update
• Check for outdated information
• Update API docs if endpoints changed
• Sync knowledge graph with changes

Monthly

• Audit knowledge base completeness
• Review and improve unclear docs
• Update architecture diagrams
• Clean up obsolete content

Quarterly

• Major knowledge base review
• Reorganize structure if needed
• Gather user feedback
• Plan improvements

Tools & Technologies

Storage Options

Generation Tools

• TypeDoc: Generate docs from TypeScript
• JSDoc: Generate docs from JavaScript
• Swagger/OpenAPI: Generate API docs
• Mermaid: Generate diagrams
• Supabase CLI: Generate DB types

Common Pitfalls

• Over-documentation: Don't document the obvious
• Under-documentation: Don't assume knowledge
• Outdated docs: Worse than no docs
• Scattered information: Consolidate related knowledge
• Missing context: Always explain the "why"
• Poor organization: Make it findable
• No maintenance: Knowledge bases decay
• One format only: Use appropriate formats for different needs