Agent Skills: Knowledge Architecture Skill

Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

Knowledge Architecture Skill

Purpose

Create a durable, file-backed knowledge system that helps the team keep shared context, decisions, rules, and open questions in one place.

This milestone is static-first:

• no hooks
• no MCP
• no custom tools
• no runtime memory engine

Use markdown files, links, and clear ownership.

When to Use

• Starting a knowledge base for a product or domain
• Reorganizing scattered planning notes into canonical files
• Turning repeated context into stable rules and references
• Establishing decision, quality, and review links around a domain

Canonical Inputs

• templates/knowledge/index.md
• templates/knowledge/domain.md
• templates/knowledge/knowledge.md
• templates/knowledge/hypotheses.md
• templates/knowledge/rules.md
• docs/knowledge/README.md

Related records:

• templates/decisions/decision.md
• templates/quality/gate.md
• templates/review/maintenance-review.md

Target Structure

Prefer this shape:

docs/knowledge/
├── README.md
├── index.md
├── domains/
│   └── <domain>.md
├── entries/
│   └── <topic>.md
├── hypotheses.md
└── rules.md

Workflow

1. Define scope

   • What product, system, or domain does this cover?
   • What should be durable vs still uncertain?

2. Create the index

   • Start from templates/knowledge/index.md.
   • Capture domains, key knowledge, rules, open hypotheses, and linked records.

3. Map domains

   • Create one file per meaningful domain from templates/knowledge/domain.md.
   • Keep boundaries explicit.

4. Capture atomic knowledge

   • Use templates/knowledge/knowledge.md for durable facts, patterns, or references.
   • Favor small entries with strong links.

5. Track uncertainty

   • Use templates/knowledge/hypotheses.md for claims that need validation.
   • Every hypothesis should have an owner or next validation step.

6. Write rules

   • Use templates/knowledge/rules.md for stable operating rules.
   • Link each rule to evidence, decisions, or prior incidents when possible.

7. Link adjacent systems

   • Stable choices belong in docs/decisions/.
   • Repeatable checks belong in docs/quality/.
   • Recurring health checks belong in docs/reviews/maintenance/.

Writing Rules

• Keep titles crisp.
• Prefer one idea per file.
• Mark uncertainty instead of hiding it.
• Link laterally across knowledge, decisions, quality, and reviews.
• Avoid session-specific chatter.

Done Criteria

• docs/knowledge/index.md exists or is updated.
• Core domains are listed.
• Durable knowledge is separated from hypotheses.
• Rules are explicit.
• Related decisions, gates, and reviews are linked.

Anti-Patterns

• Giant undifferentiated notes
• Rules without rationale
• Decisions embedded in random meeting notes
• Hypotheses presented as settled facts
• Runtime tooling assumptions in milestone 1

Anti-Rationalization Table

| Excuse | Counter | |--------|---------| | "We can organize the knowledge base later" | Disorganized knowledge is lost knowledge. Structure it while the context is fresh. | | "One big document is easier to maintain" | Giant undifferentiated notes are impossible to navigate. Split by domain. | | "Hypotheses should be marked as facts for clarity" | Marking uncertainty as fact corrupts the knowledge base. Be honest about what is known. | | "Rules don't need rationale" | Rules without rationale are ignored. Explain the why behind each rule. | | "We don't need a knowledge base for this project" | Every project accumulates knowledge. Without a home for it, it lives in people's heads. |