agents-sync
Layer 10 of the knowledge-sync-loop — the agent definitions surface validator. Use when the user asks 'are all agents registered', 'is the agent fleet healthy', 'what are the NCCA subject specialists'
SKILL.md.agents/skills/agents-sync/SKILL.md
GitHubAgent Definitions Sync (Layer 10 of the knowledge-sync-loop)
The Layer 10 of the 10-layer pull-based sync architecture. Validates the 188 agent files + the 12-agent fleet + the 8 NCCA subject specialists.
Why Layer 10?
The 9-layer architecture covered 12 of the 14 knowledge surfaces. The next-biggest remaining gap was the agent definitions surface - the 188 .py agent files in 7 subdirs (agents/ + agents/adk/ + agents/agno/ + agents/api/ + agents/tools/ + agents/tuatha/ + agents/meaisinfhoghlaim/).
Agent definition drift is silent: when a developer adds a new agent
to the 12-agent fleet but doesn't register it in agent_registry.py
- doesn't update the routing keywords + doesn't add an AGENTS.md, the breakage doesn't surface until the next agent registration test. The 8 NCCA subject specialists (in agents/tuatha/agents/) are particularly prone to drift because they were added incrementally.
Layer 10 closes the agent definitions gap.
What Layer 10 covers
bash scripts/sync/agents.sh walks the 7 agent subdirs + produces a
per-subdir report to stedding/sync-reports/agents-{date}.md with:
- The per-subdir .py file counts
- The 5 AGENTS.md files
- The 8 NCCA subject specialists (in agents/tuatha/agents/)
- The 12-agent fleet + the 4 NCCA subjects + the remaining subdirs
- Drift detection (unregistered agents + stale model refs)
The orchestrator mise run sync:agents runs all 5 sub-layers +
writes a unified report to stedding/sync-reports/agents-all-{date}.md.
The 5 sub-layers
| Sub-layer | Task | What it does |
|---|---|---|
| 1 | sync:agents-drift |
Detects unregistered agents + stale model refs |
| 2 | sync:agents-ccc |
Appends the 25th CCC concept guide (agent-fleet-search) + reindex |
| 3 | sync:agents-cognee |
Ingests the 188 agent files into the 14th Cognee cluster (agent_definitions) |
| 4 | sync:agents-test |
Runs the agent registration test + reports pass/fail per agent |
| 5 | sync:agents-lint |
Per-subdir stats (7 subdirs + 5 AGENTS.md + 8 NCCA subject specialists) |
The new artifacts
| Artifact | File | Purpose |
|---|---|---|
agents-sync skill |
.agents/skills/agents-sync/SKILL.md |
this file |
| 25th CCC guide | agent-fleet-search |
surfaces the 188 agent files via CCC |
| 14th Cognee cluster | agent_definitions |
the 188 agent files |
agents_sync_health asset |
orchestration/defs/sync_assets.py |
Dagster asset |
scripts/cognee_ingest_agent_definitions.py |
ingestor | The canonical Cognee cluster ingestor |
notebooks/sync_health.py |
dashboard | Agents tab in the grouped sync-health marimo surface |
Agent definitions evolution feedback loop
The system grows its knowledge surface over time via the agent definitions evolution feedback loop:
agent file modified
→ sync:agents-cognee detects the change
→ re-cognifies the modified agent into the agent_definitions cluster
→ sync:agents-ccc updates the 25th concept guide
→ The deployment control panel (notebook 24) surfaces the change
Quick routing
| If you want to... | Do this |
|---|---|
| Check the agent fleet health | mise run sync:agents |
| See the per-subdir breakdown | cat stedding/sync-reports/agents-$(date +%Y-%m-%d).md |
| Add a new agent | Create the .py file in the right subdir + register it in agent_registry.py + add it to routing keywords + update agents/AGENTS.md + run sync:agents |
| Fix a registration drift | sync:agents-drift will list the unregistered agents; register + re-run |
| See the agent definitions dashboard | Open notebooks/sync_health.py (Agents tab) |
| Run the agent registration test | mise run agents:smoke |
Cross-references
openspec/changes/2026-08-15-knowledge-sync-loop-v1/(the foundation)openspec/changes/2026-08-15-stacks-sync-loop-v1/(Layer 8)openspec/changes/2026-08-15-dlt-sync-loop-v1/(Layer 9)agents/(the 12-agent fleet + the 188 .py files)agents/AGENTS.md(the canonical agent documentation)agents/tuatha/(the 8 NCCA subject specialists)