Skip to content

jacob-balslev/skill-graph / marketplace/skills/knowledge-modeling

knowledge-modeling

Unverified

Knowledge modeling: choosing and maintaining the representation paradigm (graphs, frames, rules, hybrids) for domain knowledge based on primary query patterns. Do NOT use for Design the database tables and foreign keys for this schema. Do NOT use for I just need a clean IS-A category hierarchy with no rules or graph behavior. Do NOT use for I need formal OWL axioms with class restrictions and reasoning semantics. Do NOT use for I want the exact edge labels between concepts. Do NOT use for Abstract the domain into entities and relationships in human-readable terms before any database talk. Do NOT use for paradigm choice and informal/hybrid representation (use ontology-modeling). Do NOT use for graph structure and representation choice (use semantic-relations). Do NOT use for multi-paradigm and graph modeling (use taxonomy-design).

Knowledge Modeling

Concept of the skill

Knowledge modeling is the discipline of choosing a representation paradigm — knowledge graph (nodes + edges + properties), frames (structured records with slots and inheritance), semantic network (labelled IS-A/HAS-A concepts), production rules (IF→THEN decision logic), concept map (propositions for human reading), procedural ontology / PKO (decisions + state changes + triggers as first-class entities), or hybrid — that fits how the knowledge will be queried, reasoned over, and maintained. Drawing from Newell's knowledge level and Brachman & Levesque's KR&R tradition, it treats representation as a strategic choice with explicit expressiveness-tractability trade-offs rather than as a default.

Replaces "use whichever knowledge format is familiar" with paradigm choice driven by the dominant query pattern. Solves the problem that AI-agent systems are knowledge systems in disguise — every SKILL.md is a knowledge artefact, every reference doc, every routing rule, every memory file, every decision record. The question is never whether the workspace has a knowledge model (it always does, even when implicit), but whether the model fits the dominant query pattern. Multi-hop reasoning needs a graph. Decision logic needs production rules. Object-like domain entities need frames. "Why did the agent decide X?" needs a procedural ontology. Pick the wrong paradigm and the agent's reasoning breaks against the representation rather than against the domain. The expressiveness-vs-tractability trade-off is non-negotiable: more expressive representations (OWL-DL, full first-order logic) admit fewer fast queries; more tractable representations (property graphs, key-value) admit fewer formal proofs. For most product teams the right answer is "Markdown with conventions" — which is what a SKILL.md is — not formal ontology; escalate formality only when automated reasoning or multi-system interop genuinely requires it.

Distinct from conceptual-modeling, which is the human-readable domain analysis layer (entities, attributes, relationships, cardinality) — this skill is the representation-strategy layer above that (choosing between graphs, frames, rules, hybrids). Distinct from context-graph, which is one specific application of knowledge modeling (the multi-graph context architecture for skills + docs + memory + scripts) — this skill is the general theory it draws on. Distinct from skill-infrastructure, which is the live tooling that maintains the skill library — this skill is the theory of what kind of knowledge artefact a SKILL.md is and why frames are the right paradigm for one. Distinct from database-migration / entity-relationship-modeling (concerns data structure — tables, columns, FK constraints; this skill concerns meaning structure). Distinct from ontology-modeling (formal axioms with reasoning constraints — the layer above this skill) and from semantic-relations (typing individual concept edges). Knowledge modeling is to a knowledge artefact what choosing between blueprint, schematic, exploded view, flowchart, and storyboard is to documenting a complex device — the device hasn't changed, but each format makes different questions easy or impossible to answer. A blueprint answers 'where does this part go?'; a schematic answers 'what is connected to what?'; a flowchart answers 'what happens when?'. Showing a customer a wiring schematic when they want to know how the product is assembled is choosing the wrong representation, not failing at the documentation. The wrong mental model is that any structured format is a knowledge model — JSON files, Markdown docs, database tables are all "knowledge" in a loose sense. They are not, in the technical sense this skill cares about. Knowledge is not data: data records facts ("order #1247 has status refunded"); knowledge encodes the judgment and context needed to act on those facts ("refunds after 30 days require manager approval"; "the upstream fulfilment pipeline has a known 48-hour delay"). The agent with only the data hallucinates the policy; the agent with the knowledge applies it. Adjacent misconceptions: that one paradigm fits all (it does not — most real systems are hybrid: graph for entities and relationships, rules for decision logic, frames for stable domain objects, PKO when decision-trace replay matters); that more formal is more capable (it is not — OWL-DL admits fewer fast queries than property graphs; for most product teams Markdown with conventions is better than RDF triples); that GraphRAG always beats plain RAG (it does not — GraphRAG only wins when the underlying graph is well modelled; a sparse, mislabelled, or synonym-inconsistent graph retrieves worse than plain vector search because the structure becomes noise); and that knowledge once captured is durable (it is not — knowledge has a lifecycle: Create → Validate → Publish → Use → Monitor → Update → Retire; periodic currency checks are scheduled, not aspirational, because domain knowledge drifts faster than code).

Coverage

The representation-strategy layer above conceptual modeling and below formal ontology. Names seven knowledge-representation paradigms — Knowledge Graph, Frames, Semantic Network, Production Rules, Concept Map, Process / Procedural Ontology (PKO), Hybrid — with structure, best-for, and weakness for each. Specifies the tacit-to-explicit knowledge acquisition pipeline that converts what experts know-but-cannot-articulate into computable form (elicitation → articulation → formalization → expert validation → encoding) and the five knowledge sources (domain experts, documentation, existing code, user behaviour, failure post-mortems). Lays out knowledge-graph design principles: reify when a relationship has properties, separate schema-level from instance-level, label edges precisely (created_by not related_to), enforce bidirectional naming, minimise redundancy. Covers the four validation types (completeness / consistency / relevance / currency) plus expert walkthrough. Walks the seven-phase knowledge lifecycle (Create → Validate → Publish → Use → Monitor → Update → Retire) with each phase's failure mode. Maps the theory to AI-agent systems: skills as frames, routing as production rules, memory as a knowledge graph with temporal properties. Devotes a full section to GraphRAG with five concrete patterns (entity-anchored retrieval, relationship-aware context, path-based reasoning, subgraph summarization, hybrid vector + graph) and the rules for when graph-grounded retrieval actually beats plain vector RAG. Closes with the representation-tradeoff matrix between expressiveness and tractability across reasoning, querying, maintenance, and human readability.

Philosophy of the skill

Knowledge is not data. Data records facts; knowledge encodes the judgment and context needed to act on those facts. A database stores that an order has status refunded. Knowledge captures that a refund after thirty days requires manager approval, that the customer's lifetime value should influence the response, and that the upstream fulfilment pipeline has a known forty-eight-hour delay. The agent that has only the data hallucinates the policy; the agent that has the knowledge applies it.

AI-agent systems are knowledge systems in disguise. Every SKILL.md is a knowledge artefact. Every reference doc is a knowledge artefact. Every routing rule, every memory file, every decision record is a knowledge artefact. The question is not whether the workspace has a knowledge model — it always does, even when implicit — but whether the model fits the dominant query pattern. Multi-hop reasoning needs a graph. Decision logic needs production rules. Object-like domain entities need frames. "Why did the agent decide X?" needs a procedural ontology. Pick the wrong paradigm and the agent's reasoning breaks against the representation rather than against the domain.

The representation-vs-reasoning tradeoff is non-negotiable. More expressive representations (OWL-DL, full first-order logic) admit fewer fast queries; more tractable representations (property graphs, key-value) admit fewer formal proofs. For most product teams the right answer is "Markdown with conventions" — which is what a SKILL.md is — not formal ontology. Escalate formality only when automated reasoning or multi-system interop demands it.

1. Knowledge-Representation Paradigms

ParadigmStructureBest forWeakness
Knowledge GraphNodes (entities) + edges (relationships) + propertiesMulti-hop reasoning, entity disambiguation, relationship discoveryHard to express rules and constraints
FramesStructured records with slots, default values, inheritanceObject-like domain modeling; defaults and exceptionsLimited relationship expressiveness
Semantic NetworkLabelled graph of concepts with IS-A / HAS-A linksConcept navigation; vocabulary organisationNo formal semantics; ambiguous edges
Production RulesIF condition THEN actionDecision logic; business rules; routingPoor at representing structural knowledge
Concept MapPropositions as labelled connections between conceptsLearning, communication, knowledge auditInformal; not directly computable
Process / Procedural Ontology (PKO)Decisions, state changes, procedural steps, and triggers as first-class entitiesAgent memory with "why / how" traces; audit trails; workflow capture; multi-agent orchestrationHeavy to author; easy to over-instrument
HybridMix of graph + rules + framesReal-world systemsComplexity management

Choosing the paradigm

Pick the paradigm by the primary query pattern the system needs to answer:

  • "What is related to X?" → graph
  • "What should I do when X?" → production rules
  • "What are the properties of X?" → frames
  • "What concepts connect these ideas, for a human reader?" → concept map
  • "Why did the agent decide X, and through what intermediate states?" → procedural ontology (PKO)

Most real systems converge on a hybrid: a knowledge graph for entities and relationships, plus production rules for decision logic, plus frames for stable domain objects, plus a PKO layer when decision-trace replay matters.

2. Knowledge Acquisition

Sources and methods

SourceMethodOutput
Domain expertsStructured interviews, protocol analysisExplicit rules, decision criteria
DocumentationDocument analysis, extractionFacts, procedures, constraints
Existing codeCode archaeology, pattern miningImplicit rules, edge cases
User behaviourTask analysis, usage logsTacit knowledge, workarounds
FailuresPost-mortem analysis, bug reportsNegative knowledge — what NOT to do

Tacit-to-explicit pipeline

Tacit knowledge (in expert's head)
   │
   ▼
Elicitation       — interview, observation
   │
   ▼
Articulation      — natural-language rules
   │
   ▼
Formalization    — structured representation
   │
   ▼
Validation       — expert review against real scenarios
   │
   ▼
Encoding         — computable form

Rules:

  • The most valuable knowledge is tacit — things experts do automatically but cannot articulate without prompting. Plan elicitation, not just transcription.
  • Negative knowledge ("never do X because Y happened") is as valuable as positive knowledge. Capture failures.
  • Knowledge mined from code is structurally incomplete: the code captures the what, not the why. Pair code archaeology with expert review.

3. Knowledge-Graph Design Principles

Node and edge conventions

ElementConventionExample
Entity nodeNoun, PascalCaseOrder, Product, Customer
Concept nodeNoun phrase representing an ideaRefundPolicy, PricingStrategy
Relationship edgeVerb phrase, directed, labelledOrder -[placed_by]-> Customer
PropertyKey-value on node or edgeOrder.total_amount = 4599
Type edgeIS-A classificationDigitalProduct -[is_a]-> Product
Part edgePart-wholeLineItem -[part_of]-> Order

Five graph principles

PrincipleRule
Reify when neededIf a relationship carries properties (date, amount, status), promote it to a node
Separate structure from contentSchema nodes (types, relations) vs instance nodes (specific entities)
Label preciselycreated_by not related_to; specificity enables reasoning
Bidirectional namingEvery edge should read naturally in both directions: Order -[placed_by]-> Customer and Customer -[placed]-> Order
Minimal redundancyDerive rather than duplicate; if a value can be computed from the graph, don't store it twice

4. Knowledge Validation

Validation typeWhat it catches
Completeness checkMissing entities, relationships, or rules for known scenarios
Consistency checkContradictory rules or overlapping categories
Relevance checkKnowledge that exists in the model but serves no real query or decision
Currency checkKnowledge that was true when captured but has since changed
Expert walkthroughExpert reviews the model against real scenarios; catches implicit assumptions

Rules:

  • Validate against real scenarios, not abstract correctness. The walkthrough catches what the schema-checker can't.
  • Schedule periodic currency checks — domain knowledge drifts faster than code.
  • Every piece of knowledge in the base should answer a question someone actually asks. Knowledge nobody queries is dead weight that pulls retrieval signal-to-noise down.

5. Knowledge Lifecycle

Create  →  Validate  →  Publish  →  Use  →  Monitor  →  Update  →  (Retire)
PhaseKey activityFailure mode
CreateAcquire from source; formaliseIncomplete capture; missing tacit knowledge
ValidateExpert review; scenario testingRubber-stamp approval; untested edge cases
PublishMake available to consumers (agents, APIs, UIs)Poor discoverability; stale indexes
UseRuntime queries; decision supportOver-reliance on outdated knowledge
MonitorTrack usage, accuracy, relevanceNo feedback loop; zombie knowledge
UpdateRevise based on new information or feedbackPartial updates; inconsistencies between updated and stale parts
RetireRemove or archive obsolete knowledgeHoarding; false confidence in expired material

6. Application to AI-Agent Systems

Agent componentKnowledge-modeling concern
Skill libraryEach skill is a knowledge artefact; the skill index is a knowledge graph
Context engineeringSelecting which knowledge to load into a finite context window
Routing / dispatchProduction rules mapping inputs to skill / agent selection
Memory systemLong-term persistence with freshness management
EvaluationValidating that knowledge actually improves agent output

The mappings:

  • Skills are frames. Structured slots (triggers, keywords, body, references) with defaults and inheritance.
  • The routing system is a production-rule engine. IF keyword matches THEN load skill.
  • The memory system is a knowledge graph with temporal properties. Freshness, drift, decay all live on the edges.
  • Context engineering is knowledge selection under token-budget constraints. A subset-selection problem with quality and cost both as objectives.

6.1 GraphRAG — grounding retrieval in a knowledge graph

Plain Retrieval-Augmented Generation retrieves unordered text chunks by vector similarity. This fails on multi-entity questions, on disambiguation, and on questions whose answer depends on how entities relate — vector similarity finds "topically close" passages, not "structurally connected" facts. GraphRAG grounds retrieval in a knowledge graph, so the model receives typed entities and labelled edges instead of a bag of passages.

PatternWhat it doesWhen it beats plain RAG
Entity-anchored retrievalResolve prompt mentions to graph nodes, then expand N hopsMulti-entity questions; disambiguation across namespaces
Relationship-aware contextInclude labelled edges alongside retrieved nodesQuestions about how two things relate, not just what they are
Path-based reasoningReturn the concrete path between two nodes as context"Why is X connected to Y?" questions
Subgraph summarizationSummarise a relevant subgraph into natural language before passing to the LLMReduces hallucination on multi-hop and aggregation questions
Hybrid (vector + graph)Vector retrieval seeds entry points; graph expansion adds structureCorpora where neither pure approach wins alone

Rules:

  • GraphRAG only wins when the underlying graph is well modelled. A sparse, mislabelled, or synonym-inconsistent graph retrieves worse than plain vector search — the structure becomes noise.
  • Reserve GraphRAG for questions whose answer depends on relationships between entities. Single-entity attribute questions ("what is X's status?") do not benefit.
  • Return the source nodes and edges alongside the LLM's answer so the user can verify the retrieval path. This is GraphRAG's explainability advantage over plain RAG; surface it.
  • At minimum, enforce SKOS-grade vocabulary discipline (consistent labels, broader / narrower) before building a GraphRAG pipeline.
  • GraphRAG does not replace a good knowledge graph — it is a retrieval pattern on top of one. Invest in the graph first; the retrieval pattern is downstream.

7. Representation Trade-offs

DimensionMore expressiveMore tractable
ReasoningOWL-DL, full first-order logicProperty graphs, key-value
QueryingSPARQL, CypherSimple lookups, keyword search
MaintenanceFormal schemas with constraintsPlain text with conventions
Human readabilityConcept maps, MarkdownJSON-LD, RDF triples

Rules:

  • For most product teams the right answer is "Markdown with conventions" (what a SKILL.md is) rather than formal ontology.
  • Escalate formality only when automated reasoning or multi-system interop is genuinely required.
  • The best representation is the one that domain experts can validate and developers can query. If either side struggles, the choice is wrong even when the formalism is technically correct.

Verification

  • Each knowledge artefact has an explicit source and a validation status
  • The chosen representation paradigm matches the primary query pattern — not the team's familiarity with one paradigm
  • Tacit knowledge was elicited (interview / observation) — not just documented knowledge transcribed
  • A lifecycle / freshness mechanism exists for ongoing knowledge maintenance; periodic currency checks are scheduled, not aspirational
  • Knowledge consumers (agents, UIs, APIs) can discover and access the relevant knowledge through structured indexes — discovery is not "remember the file path"
  • Validation is run against real scenarios, not abstract completeness — including failure / negative scenarios
  • If GraphRAG is in use, the underlying graph passes vocabulary discipline (consistent labels, broader / narrower) and the retrieval path is surfaced alongside the LLM's answer

Do NOT Use When

Use insteadWhen
conceptual-modelingPerforming the human-readable domain analysis (entities, attributes, relationships, cardinality) — that's the layer below this skill
entity-relationship-modelingDesigning database tables, foreign keys, normalization — data structure, not meaning structure
taxonomy-designBuilding a pure IS-A classification hierarchy with no rules or graph behaviour
ontology-modelingDefining formal axioms with OWL / RDFS, class restrictions, automated-reasoning constraints — the layer above this skill
semantic-relationsPicking exact edge labels — hypernymy, meronymy, synonymy, polysemy, troponymy
skill-infrastructureMaintaining the live skill library (census, overlap detection, drift checks) — knowledge-modeling is the theory, skill-infrastructure is the operations
context-graphDesigning the multi-graph topology of a workspace — that is one application of this skill, not the theory itself

Key Sources

  • Newell, A. (1982). "The Knowledge Level." Artificial Intelligence, 18(1), 87-127. The foundational paper distinguishing the knowledge level (rationality, goals, body of knowledge) from the symbol level (representation implementation). Establishes that representation choices are about which abstraction layer is appropriate, not which formalism is most powerful.
  • Brachman, R. J., & Levesque, H. J. (2004). Knowledge Representation and Reasoning. Morgan Kaufmann. The canonical textbook on KR&R: the expressiveness-tractability trade-off, description logics, frames, production systems, default reasoning. The reference for paradigm choice.
  • Sowa, J. F. (2000). Knowledge Representation: Logical, Philosophical, and Computational Foundations. Brooks/Cole. Encyclopedic synthesis of KR traditions from Aristotle through conceptual graphs. The single best reference for how paradigms relate to each other.
  • Minsky, M. (1974). "A Framework for Representing Knowledge." MIT-AI Memo 306. The foundational paper introducing frames: structured records with slots, defaults, and inheritance. Frames remain the right paradigm for object-like domain entities with stable structure.
  • W3C (2009). SKOS Simple Knowledge Organization System Reference. The normative low-cost vocabulary layer for concepts, labels, broader/narrower links, related links, and concept schemes.
  • Edge et al. (2024). "From Local to Global: A Graph RAG Approach to Query-Focused Summarization." arXiv:2404.16130. Useful grounding for when graph-structured retrieval helps sensemaking over large corpora.
  • Gruber, T. R. (1993). "A Translation Approach to Portable Ontology Specifications." Knowledge Acquisition, 5(2), 199-220. The definition of ontology as "a specification of a conceptualization" and the formal grounding for interoperable knowledge artefacts.
  • Quillian, M. R. (1968). "Semantic Memory." In M. Minsky (Ed.), Semantic Information Processing. MIT Press. The original semantic-network paper; the cognitive-science origin of labelled concept graphs.
  • Novak, J. D., & Cañas, A. J. (2008). The Theory Underlying Concept Maps and How to Construct Them. IHMC. The methodology for concept maps as a knowledge-elicitation and human-communication tool.
  • Edge, D., Trinh, H., Cheng, N., et al. (2024). "From Local to Global: A Graph RAG Approach to Query-Focused Summarization." Microsoft Research. The reference statement of GraphRAG as a retrieval pattern over modelled knowledge graphs.
  • W3C. SKOS Reference. The Simple Knowledge Organization System specification; the minimal vocabulary discipline (broader/narrower/related, prefLabel/altLabel) that knowledge-graph quality depends on.
  • Studer, R., Benjamins, V. R., & Fensel, D. (1998). "Knowledge Engineering: Principles and Methods." Data & Knowledge Engineering, 25(1-2), 161-197. Survey of the acquisition pipeline (elicitation → modeling → validation) and the methodological tradition behind it.

Skill Graph context

Classification

  • Subject: knowledge-organization
  • Public: true
  • Domain: foundations/knowledge
  • Scope: Teaches choosing and maintaining the representation paradigm for domain knowledge: graphs, frames, semantic networks, production rules, concept maps, procedural ontologies, GraphRAG, or hybrids. Excludes stakeholder-readable conceptual modeling, database schema design, pure taxonomy hierarchy, formal ontology axioms, exact semantic edge labeling, and live skill-library tooling.

When to use

  • Should this domain knowledge be a graph, a set of rules, a frame structure, or a hybrid?
  • Our skill library keeps adding prose but the agent can't reason over relationships — which representation should change?
  • The agent retrieves topically similar passages but misses structurally related facts — is GraphRAG the right shift?
  • How do I capture decision traces and triggers as first-class entities so the agent can replay why it chose Y?
  • We want to validate the knowledge base against real scenarios — what completeness / consistency / relevance / currency checks should run?
  • Triggers: knowledge-modeling, knowledge representation, knowledge graph modeling, GraphRAG modeling, representation paradigm

Not for

  • Design the database tables and foreign keys for this schema.
  • I just need a clean IS-A category hierarchy with no rules or graph behavior.
  • I need formal OWL axioms with class restrictions and reasoning semantics.
  • I want the exact edge labels between concepts.
  • Abstract the domain into entities and relationships in human-readable terms before any database talk.
  • Owned by ontology-modeling: paradigm choice and informal/hybrid representation
  • Owned by semantic-relations: graph structure and representation choice
  • Owned by taxonomy-design: multi-paradigm and graph modeling

Related skills

  • Verify with: conceptual-modeling, ontology-modeling
  • Related: skill-infrastructure, entity-relationship-modeling, context-graph, context-engineering, conceptual-modeling, ontology-modeling, taxonomy-design, semantic-relations

Concept

  • Mental model: |
  • Purpose: |
  • Boundary: |
  • Analogy: Knowledge modeling is to a knowledge artefact what choosing between blueprint, schematic, exploded view, flowchart, and storyboard is to documenting a complex device — the device hasn't changed, but each format makes different questions easy or impossible to answer. A blueprint answers 'where does this part go?'; a schematic answers 'what is connected to what?'; a flowchart answers 'what happens when?'. Showing a customer a wiring schematic when they want to know how the product is assembled is choosing the wrong representation, not failing at the documentation.
  • Common misconception: |

Grounding

  • Mode: hybrid
  • Truth sources: https://doi.org/10.1016/0004-3702(82)90012-1, https://books.google.com/books/about/Knowledge_Representation_and_Reasoning.html?id=ln6Ux-EZm6YC, https://courses.media.mit.edu/2004spring/mas966/Minsky%201974%20Framework%20for%20knowledge.pdf, https://www.w3.org/TR/skos-reference/, https://arxiv.org/abs/2404.16130

Keywords

  • knowledge representation, knowledge graph, frames and slots, production rules, semantic network, concept map, procedural ontology, hybrid knowledge representation, tacit to explicit knowledge, knowledge acquisition pipeline
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall