# Homoiconic Meta Schema

> |

- **Type:** Skill
- **Install:** `agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-homoiconic-meta-schema`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AnthonyAlcaraz](https://agentstack.voostack.com/s/anthonyalcaraz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills/tree/main/skills/knowledge-representation/homoiconic-meta-schema
- **Website:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

## Install

```sh
agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-homoiconic-meta-schema
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Homoiconic Meta-Schema

## Overview

Agent-friendly knowledge graphs need **homoiconicity**: code and data in the
same representation, so agents can inspect and modify their own operational
logic. Ch3 gives two constructs.

**Meta-knowledge structures (Example 3-6).** A metaschema describes the schema
itself — it defines what an `EntityType` is (a name, a description, a list of
property definitions). Then domain knowledge is stored using the same
representation: a `Person` entity-type is just data with `name`, `birth_date`,
`occupation` properties. The syntax of schema and data is identical. This skill
runs the same validation at both levels: `validate_entity_type` checks a type
against the metaschema; `validate_data_against_type` checks an instance against
its type. Same machinery, two levels — that is the homoiconic property doing
real work. It lets agents reason about knowledge completeness, dynamically
update schemas as they learn, and self-evolve without external reprogramming.

**Executable knowledge patterns (Example 3-7).** Operational rules become
first-class graph entities. A `Rule` has descriptive metadata, a `condition`
(graph pattern match), and an `action` (tiered `WHEN ... THEN SET ...` /
`ELSE`). Because the rule is data, agents can reason about rules, not just
follow them — discover, modify, create rules, and explain decisions by citing
the rule. This skill parses the tiered action, validates the rule has a
parseable clause, and evaluates it in source order against facts
(`DetermineCustomerSegment`: 25 purchases -> Premium, 15 -> Regular, 3 ->
Basic). The DevOps `OperationalRule` (`ValidateProductionDeployment`) is the
same construct applied to infrastructure.

## When to Use

- Building agents that reason about or modify their own schema (Ch7 self-evolution)
- Storing business/operational rules as queryable graph data, not hidden code
- Validating agent-proposed schema extensions before applying them
- Representing the ontology itself as data the agent can query

Phrases: "homoiconic", "metaschema", "schema as data", "entity-type definition",
"executable knowledge", "rule as graph entity", "self-evolving schema",
"meta-knowledge".

## When NOT to Use

- **Static schemas.** If the schema never changes, a plain class/struct is
  simpler; homoiconicity pays off only when the agent modifies its own structure.
- **General code execution.** `evaluate_rule` interprets a constrained tiered
  WHEN/THEN/ELSE grammar, NOT arbitrary code. Do not treat it as an interpreter
  for untrusted input.
- **Schema PATTERN selection.** Use `schema-pattern-selector` to choose
  Event-Centric vs Multi-Perspective etc.; this validates the homoiconic
  meta-level and executable rules.

## Process

| Step | Input | Action | Output | Verification |
|------|-------|--------|--------|--------------|
| 1 | entity-type definition dict | `lib.validate_entity_type(def)` | `{valid, errors}` | name required, property names unique, types valid |
| 2 | entity-type + data instance | `lib.validate_data_against_type(type, instance)` | `{valid, errors}` | required props present, value types match (same validator level) |
| 3 | Rule dict (name, condition, action) | `lib.validate_rule(rule)` | `{valid, errors, parsed_clauses}` | action must parse to >= 1 WHEN clause |
| 4 | action text | `lib.parse_action(text)` | `{when: [...], else: {...}}` in source order | tiered order preserved |
| 5 | Rule + facts dict | `lib.evaluate_rule(rule, facts)` | `{field: value}` or None | first matching WHEN by source order, then ELSE |

## Rationalizations

| Agent rationalization | Documented rebuttal |
|------------------------|--------------------|
| "Schema and data are different things — keep the schema in code." | That is exactly the non-homoiconic system the chapter contrasts against. When schema lives in code, the agent cannot inspect or evolve it. Storing the entity-type AS DATA (Example 3-6) is what lets the agent reason about completeness and self-evolve. |
| "Business rules belong in application code, not the graph." | Then the agent can follow rules but never reason about them, modify them, or explain decisions by citing them. Example 3-7 makes rules first-class graph entities precisely to unlock those capabilities. Implicit procedural knowledge becomes explicit, queryable structure. |
| "I'll evaluate WHEN clauses in any order." | Tiered rules depend on source order: `>20 -> Premium` must be checked before `>10 -> Regular`, or 25 purchases wrongly matches Regular first. `parse_action` and `evaluate_rule` preserve order on purpose. |
| "Duplicate property names are harmless." | The chapter's AI-assisted ontology validation explicitly checks "property names are unique". Duplicates make the type ambiguous; the validator fails them. |
| "Skip data-instance validation — the type definition is enough." | The homoiconic value is that the SAME validator works at both levels. Validating instances against their type is what catches the missing-required-field and wrong-type errors before they corrupt the graph. |

## Red Flags

- **Entity-type passes but instances of it keep failing required-field checks.**
  The type declares fields the data pipeline never populates — the schema and the
  extractor disagree.
- **A Rule validates but `evaluate_rule` returns None for normal inputs.** The
  action clauses don't cover the input range and there's no ELSE — add a default
  tier.
- **WHEN clauses out of order in the source.** Tiered evaluation will match the
  wrong tier; reorder most-specific-first.
- **Agent proposes a schema extension with a property type outside the allowed
  set.** Reject and surface — unchecked types are how schema drift enters a
  self-evolving system.

## Non-Negotiable Verification

1. **Run the benchmark battery.** `python cli.py benchmark` must report 10/10:
   - valid Person type passes; missing-name, duplicate-property, invalid-type fail
   - data instance: required-present passes, missing-required and wrong-type fail
   - rule parses 2 WHEN + 1 ELSE; tiered eval gives 25->Premium, 15->Regular, 3->Basic
   - rule missing action fails
2. **Run the scenario.** `python cli.py scenario customer-segment` validates the
   Person type as data, validates an instance against it, and evaluates the
   segmentation rule across tiers.
3. **Verify CLI help.** `python cli.py --help` exits 0 and prints this SKILL.md
   description (so any harness can discover the skill from --help).

## Security Posture

- **Prompt injection.** Entity-type definitions and Rule actions are untrusted
  data, often agent-proposed. The evaluator interprets only the constrained
  WHEN/THEN/ELSE grammar - never eval/exec - so injected text fails parsing
  rather than executing. A syntactically valid rule can still encode malicious
  LOGIC; review agent-proposed rules before storing them in the graph.
- **Data exfiltration.** No network calls, no file writes. Facts passed to
  `evaluate_rule` stay in-process; results go to stdout and the caller owns
  downstream piping.
- **Privilege escalation.** Self-modifying schemas are the escalation surface:
  an unchecked schema extension or rule rewrite widens what the agent may later
  assert. The validator rejects out-of-set property types, and rule evaluation
  returns a plain dict - it never mutates the graph or grants a capability;
  applying changes is a separate, gated step.

## Source Attribution

Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge
Representation, section "Homoiconic Knowledge Representation": meta-knowledge
structures (Example 3-6, the metaschema + Person entity-type) and executable
knowledge patterns (Example 3-7, the DetermineCustomerSegment Rule). The DevOps
`OperationalRule` (`ValidateProductionDeployment`) in the chapter's "Homoiconic
Knowledge Representation for Agent Adaptability" section is the same construct
applied to infrastructure, feeding the Ch7 self-evolution work.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** [AnthonyAlcaraz/agentic-graph-rag-skills](https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills)
- **License:** MIT
- **Homepage:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anthonyalcaraz-agentic-graph-rag-skills-homoiconic-meta-schema
- Seller: https://agentstack.voostack.com/s/anthonyalcaraz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.