Data Structure Reference

Overview

The Explorer documentation system uses a two-layer data model: base data from the ECC source files, enriched with structured metadata from a registry file. These merge at build time into a unified catalog.

Source Files (base)  +  Registry (enrichment)  =  Merged Catalog
skills/SKILL.md          catalog-registry.json       catalog.json
agents/*.md                                           + generated/*.md
commands/*.md

Layer 1: Source File Frontmatter

Each ECC source file has YAML frontmatter. The fields vary by type.

Skills (skills/*/SKILL.md)

Field	Type	Required	Example
name	string	yes	"python-patterns"
description	string	yes	"Pythonic idioms and best practices..."
origin	string	no (default: "ECC")	"ECC", "Community"

Agents (agents/*.md)

Field	Type	Required	Example
name	string	yes	"architect"
description	string	yes	"Software architecture specialist..."
tools	string[]	yes	["Read", "Grep", "Glob"]
model	enum	yes	"opus", "sonnet", "haiku"

Commands (commands/*.md)

Field	Type	Required	Example
description	string	sometimes	"Create implementation plan"

Note

About 21 of 60 command files have no YAML frontmatter at all. The sync script derives name from the # heading and description from the first paragraph.

Layer 2: Catalog Registry

File: _explorer/data/catalog-registry.json

The registry adds structured metadata that doesn’t belong in source file frontmatter: domain assignment, trigger questions, I/O contracts, profile relevance, and tool relationships.

Top-Level Structure

{
  "version": 1,
  "domains": [ ... ],
  "tools": { ... },
  "profiles": [ ... ]
}

Domain Schema

Domains represent workflow stages. Each tool belongs to one primary domain.

Field	Type	Description
id	string	URL-safe slug: "planning", "implementation", "review"
label	string	Display name: "Planning & Architecture"
icon	string	Starlight icon name
description	string	One paragraph explaining this domain’s purpose
order	integer	Sort order in navigation and listings

Tool Enrichment Schema

Tools are keyed by category:slug (e.g., "skill:python-patterns", "command:tdd", "agent:architect").

Field	Type	Required	Description
domain	string	yes	Domain ID this tool belongs to
triggerQuestion	string	no	The question a human asks that leads to this tool
input.context	string	no	What you feed the tool
input.prerequisites	string[]	no	What must exist before using it
output.artifact	string	no	What the tool produces
output.format	string	no	How the output is delivered (code files, markdown, etc.)
relatedTools	string[]	no	Other category:slug refs that pair well
profileRelevance	string[]	no	Profile IDs this tool is relevant to

Profile Schema

Profiles represent human roles with recommended workflow steps.

Field	Type	Description
id	string	URL-safe slug: "junior-dev", "senior-dev", "architect", "qa-lead"
label	string	Display name: "Junior Developer"
description	string	Role description
workflowSteps	array	Ordered steps in the workflow
workflowSteps[].order	integer	Step sequence number
workflowSteps[].toolRef	string	category:slug reference to a tool
workflowSteps[].action	string	What the user does at this step

Merged Catalog Output

The sync script merges both layers into src/content/generated/catalog.json:

{
  "skills": [
    {
      "name": "python-patterns",
      "description": "Pythonic idioms...",
      "slug": "python-patterns",
      "origin": "ECC",
      "domain": "language",
      "triggerQuestion": "What's the Pythonic way to write this?",
      "input": { "context": "Python code", "prerequisites": [] },
      "output": { "artifact": "Guidance on idioms...", "format": "knowledge" },
      "relatedTools": ["skill:python-testing", "agent:python-reviewer"],
      "profileRelevance": ["junior-dev", "senior-dev"]
    }
  ],
  "agents": [ ... ],
  "commands": [ ... ],
  "domains": [ ... ],
  "profiles": [ ... ]
}

Tools without registry entries get null for enrichment fields:

{
  "name": "some-unregistered-skill",
  "domain": null,
  "triggerQuestion": null,
  "input": null,
  "output": null,
  "relatedTools": [],
  "profileRelevance": []
}

Content Collection Schemas

The Astro content collections validate generated markdown files using Zod schemas in src/content.config.ts:

// Skills collection
z.object({
  name: z.string(),
  description: z.string(),
  origin: z.string().optional(),
  slug: z.string().optional(),
  category: z.string().optional(),
})

// Agents collection
z.object({
  name: z.string(),
  description: z.string(),
  tools: z.string().optional(),     // JSON-stringified array
  model: z.string().optional(),      // "opus" | "sonnet" | "haiku"
  slug: z.string().optional(),
  category: z.string().optional(),
})

// Commands collection
z.object({
  name: z.string(),
  description: z.string(),
  slug: z.string().optional(),
  category: z.string().optional(),
})

Caution

The content collection schemas validate frontmatter in generated markdown files. The enrichment data (domain, I/O, etc.) flows through catalog.json, not through frontmatter, so it is not validated by Zod. This is intentional - enrichment data is consumed directly by page components via fs.readFileSync.

Key Design Decisions

1. Tool keys use category:slug format to avoid collisions between a command and skill with the same name (e.g., command:eval vs skill:eval-harness).

2. One primary domain per tool. Cross-references are handled by relatedTools, not multiple domain assignments.

3. Registry is committed to git, not generated. It’s hand-authored enrichment data that evolves independently of source files.

4. catalog.json is generated and gitignored. It’s rebuilt on every sync. Components read it directly.