LLM Semantic Knowledge Contract (LSKC)

LSKC is a semantic intermediate representation for agent-facing knowledge. Instead of prose documentation, knowledge is stored as YAML specs where every statement is classified by type — facts, hard constraints, preferences, procedures — and linked into an addressable knowledge graph.

Why: agents fail on ad-hoc docs because "should" and "must" are mixed, action sequences hide inside descriptions, and nothing is referenceable. LSKC makes statement type explicit and machine-checkable, and makes every statement a graph node usable for RAG, generated docs, and impact analysis.

FACTS:
  delete_behavior:
    statement: The DELETE endpoint sets tasks.deleted_at and keeps the row.
    confidence: authoritative
CONSTRAINTS:
  no_hard_delete:
    rule: Do not remove rows from the tasks table in API request handlers.
    derived_from: ["#FACTS.delete_behavior"]

Repository layout

Everything normative and executable lives in the skill package — a self-contained directory you can drop into any agent runtime:

skills/lskc-standard/
  SKILL.md                     entry point for agents (Claude Code, Codex, ...)
  references/standard.md       the normative standard (v1.2-draft)
  references/proxy.md          markdown -> LSKC conversion procedure
  schema/lskc.schema.json      structural JSON Schema
  scripts/validate-lskc.mjs    validator (schema + semantic lint + graph checks)
  scripts/lskc-graph.mjs       knowledge-graph export (JSON / Mermaid)
  scripts/lskc-docs.mjs        Markdown docs generated from specs
  examples/minimal.lskc.yaml   minimal valid spec
example/                       real-world example specs
example/uticms/                large multi-spec knowledge base (12 linked specs)

Install as a skill

Claude Code (plugin):

/plugin marketplace add DOG729/agent-specification-standard-lskc
/plugin install lskc-standard@lskc

Claude Code (manual) / Codex / any SKILL.md-compatible runtime: copy the whole skills/lskc-standard/ directory (not just SKILL.md — the package is the unit) into your skills location, e.g. ~/.claude/skills/ or .claude/skills/ in a project.

Then ask the agent to "convert this doc to LSKC" or "validate my .lskc.yaml files" — SKILL.md routes it to the bundled references and scripts.

Use the tooling directly

npm install

npm run validate            # validate all example specs
npm run graph               # export uticms knowledge base as a graph
npm run docs                # generate Markdown docs from uticms specs

# or against your own knowledge base:
node skills/lskc-standard/scripts/validate-lskc.mjs path/to/specs
node skills/lskc-standard/scripts/lskc-graph.mjs path/to/specs --format mermaid
node skills/lskc-standard/scripts/lskc-docs.mjs path/to/specs --out docs/

The format in one minute

Root sections (required: SPEC_VERSION, CONTEXT, FACTS, CONSTRAINTS, PROCEDURES):

Section	Holds	Test
FACTS	descriptive truths	no must/should language
CONSTRAINTS	hard rules	violation = invalid state
DECISION_RULES	preferences, fallbacks	guidance, not requirement
PROCEDURES	ordered steps	executable sequence
AGENT_BEHAVIOR	pre-edit verification policy	agent-side, not runtime
SYSTEM_MODEL	topology (tables, services, layout)	shape, not assertion
CONCEPTS	glossary + light ontology	term used ambiguously? define it

Identity and links (v1.2): specs declare META.id; every entry key is a link target; ref = [spec_id]#SECTION.key. Statements link via derived_from, satisfies, governed_by, refines, supersedes, concepts. Specs link via REFERENCES.SPECS / REFERENCES.SOURCES.

Full definitions: skills/lskc-standard/references/standard.md.

Status

v1.2-draft. Benchmarks comparing agent behavior on LSKC vs ad-hoc Markdown live in a separate repository.