From ECC to Explorer

Why This Pipeline Exists

The ECC repository contains 213 tools (125 skills, 60 commands, 28 agents) as markdown files scattered across directories. Each file has its own format, varying frontmatter, and implicit relationships to other tools.

The problem: Raw files lack:

Grouping by workflow stage (which tools go together?)
Use-case context (when would I use this?)
Input/output documentation (what goes in, what comes out?)
Cross-references (which command invokes which agent?)

The solution: A build-time pipeline that reads the raw files, enriches them with structured metadata from a registry, and generates a navigable documentation site.

Source Structure

How ECC organizes its files

everything-claude-code/
├── skills/
│   ├── python-patterns/
│   │   └── SKILL.md          # Has frontmatter: name, description, origin
│   ├── tdd-workflow/
│   │   └── SKILL.md
│   └── ... (125 directories)
├── agents/
│   ├── architect.md           # Has frontmatter: name, description, tools, model
│   ├── planner.md
│   └── ... (28 files)
├── commands/
│   ├── plan.md                # Has frontmatter (some files)
│   ├── build-fix.md           # No frontmatter (21 files)
│   └── ... (60 files)
└── CHANGELOG.md

Key observations:

Skills live in subdirectories with SKILL.md files
Agents are flat markdown files with rich frontmatter (name, description, tools, model)
Commands have inconsistent frontmatter - about 21 of 60 have none at all
No metadata connects tools to each other or to workflow stages

The Sync Pipeline

The scripts/sync-content.mjs script runs before every dev and build. Here’s what it does, step by step:

Step 1: Discover Files

Uses the same logic as scripts/ci/catalog.js (the CI validation script):

// Skills: directories containing SKILL.md
skills/ -> find directories -> check for SKILL.md -> 125 found

// Agents: markdown files in agents/
agents/ -> list *.md files -> 28 found

// Commands: markdown files in commands/
commands/ -> list *.md files -> 60 found

Step 2: Parse Frontmatter

Each file is parsed with gray-matter. A fallback parser handles files where YAML chokes on unquoted colons in descriptions:

// Primary: gray-matter (standard YAML parser)
// Fallback: regex-based parser that extracts key: value pairs
// between --- delimiters

Step 3: Normalize

Missing fields are filled in:

Commands without frontmatter: name derived from # heading, description from first paragraph
All files: slug and category fields injected

Output: normalized markdown files written to src/content/generated/{skills,agents,commands}/

Step 4: Merge Registry Enrichment

The registry file (_explorer/data/catalog-registry.json) is loaded and each tool is looked up by category:slug:

// For each catalog entry:
const enrichment = registry.tools[`${category}:${slug}`];
// Merge: domain, triggerQuestion, input, output, relatedTools, profileRelevance

Tools without registry entries get null for enrichment fields.

Step 5: Write Catalog Manifest

Everything merges into src/content/generated/catalog.json:

{
  "skills": [ /* 125 enriched entries */ ],
  "agents": [ /* 28 enriched entries */ ],
  "commands": [ /* 60 enriched entries */ ],
  "domains": [ /* from registry */ ],
  "profiles": [ /* from registry */ ]
}

Step 6: Validate

The script checks:

Unregistered tools: In catalog but not in registry (warned, not blocked)
Stale entries: In registry but not in catalog (errored - tool was removed)
Coverage: Percentage of tools with registry entries

Output:

[sync] 125 skills, 60 commands, 28 agents (213 total)
[sync] WARN: 175 tools without registry entry
[sync] Registry coverage: 38/213 (17.8%)

A detailed report is written to _explorer/data/sync-report.json (gitignored).

Build Output

Astro + Starlight turns the generated content into a static site:

Content Collections

src/content/generated/skills/*.md -> Astro content collection (Zod-validated)
src/content/generated/agents/*.md -> Astro content collection
src/content/generated/commands/*.md -> Astro content collection

Static Pages Generated

Route pattern	Count	Source
`/catalog/skills/[slug]/`	125	Generated skill markdown
`/catalog/agents/[slug]/`	28	Generated agent markdown
`/catalog/commands/[slug]/`	60	Generated command markdown
`/catalog/domains/[domain]/`	7	Registry domains
`/catalog/profiles/[profile]/`	4	Registry profiles
`/guides/`, `/architecture/`	~15	Hand-authored MDX
Total	~250

Search Index

Starlight’s Pagefind integration indexes all generated HTML at build time, providing full-text search across all 250+ pages.

Evolution: Keeping It Current

Adding a new tool to ECC

1. Someone adds skills/new-skill/SKILL.md to the repo
2. Next sync: script discovers it, generates markdown + catalog entry
3. Sync warns: "[sync] WARN: skill:new-skill has no registry entry"
4. Someone adds an entry to catalog-registry.json with domain, I/O, etc.
5. Next build: tool appears in the right domain group with full metadata

Updating an existing tool

1. Someone modifies agents/architect.md (new description)
2. Next sync: script picks up the change automatically
3. Generated markdown and catalog.json reflect the new description
4. Registry enrichment (triggerQuestion, I/O) may need manual review

Removing a tool

1. Someone deletes commands/old-command.md
2. Next sync: script no longer finds it
3. Sync errors: "[sync] ERROR: registry references command:old-command which no longer exists"
4. Someone removes the entry from catalog-registry.json

File Map

File	Role	Committed?
`data/catalog-registry.json`	Hand-authored enrichment data	Yes
`scripts/sync-content.mjs`	Build-time pipeline	Yes
`src/content/generated/*.md`	Normalized markdown	No (gitignored)
`src/content/generated/catalog.json`	Merged catalog manifest	No (gitignored)
`data/sync-report.json`	Validation report	No (gitignored)