Need Standardized Structures for Agent-Consumable Markdown
Markdown docs must follow predictable, machine-reliable structures so agents can consistently locate authoritative answers.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Nina, the context engineer, needs Markdown docs to follow predictable, machine-reliable structures so agents can consistently locate authoritative answers.
Problem Context
- Markdown is the de facto interface between repos and AI systems
- “Markdown exists” isn’t sufficient; agents need consistent sections, naming, and patterns
- Different teams use different headings, nesting, and conventions
Problem Impact
- Agents miss critical constraints even when they exist in docs
- Higher hallucination rates due to ambiguity and inconsistent placement
- Increased context window waste as agents scan long, unstructured documents
Naftiko Today
- Executable YAML capability specs replace free-form documentation with a strict, machine-readable schema that agents parse deterministically rather than scanning markdown
- JSON Schema validation and Spectral ruleset (15 rules) enforce consistent structure, so every capability follows the same predictable format agents can rely on
- outputParameters with JSONPath, field renaming, and nested object support standardize what agents receive, eliminating ambiguity from unstructured docs
- Agent Skills exposure provides structured, self-describing skill metadata that agents consume directly instead of inferring from markdown
Naftiko Tomorrow
- HTML/Markdown format support (Second Alpha) will provide structured rendering rules for capability documentation that agents can parse consistently
- Tool annotations for readOnly/destructive/idempotent (Second Alpha) will add standardized behavioral metadata agents need but currently guess from docs
- JSON Schema Store publication (GA) will make the Naftiko spec format available as a recognized standard, encouraging consistent structure across tools
- TechDocs integration (Fleet First Beta) will bring standardized capability documentation into Backstage with consistent, agent-friendly formatting