Spec Discovery Skill Skill

Spec Discovery Skill

Locate specs and external request headers, extract IDs (e.g., REQ-NOTIFY-001), and return traceable metadata for downstream agents.

Variables

| Variable | Default | Description | |----------|---------|-------------| | ROOT | . | Primary repository root | | EXTRA_REPOS | [] | Additional repo roots containing specs/ | | INCLUDE_EXTERNAL_REQUESTS | true | Scan specs/external-requests/ | | OUTPUT_FORMAT | json | json or toon manifest output |

Workflow (Mandatory)

Load repositories: ROOT + EXTRA_REPOS
Walk specs: specs/, specs/external-requests/, skip specs/templates/
Parse headings: match ^#+\s*(REQ-[A-Za-z0-9_-]+)\s*:?\s*(.*)$
Normalize: path relative to repo root, anchor from ID + title
Traceability: compute SHA-256 of file content; record source_repo, path, hash
Emit manifest: sorted by repo → path → ID in JSON/TOON (see Output Schema)

Red Flags (Stop & Verify)

No IDs detected in a spec file → confirm heading format before skipping
Duplicate spec IDs across repos → flag in the manifest notes field
Missing specs/ directory → report empty result rather than failing

Output Schema

{
  "format": "spec-manifest/v1",
  "generated_at": "<ISO-8601 UTC>",
  "sources": [
    {"repository": "<repo-name>", "root": "<abs-path>"}
  ],
  "specs": [
    {
      "id": "REQ-NOTIFY-001",
      "title": "Email Sending Endpoint",
      "source_repo": "ai-dev-kit",
      "path": "specs/external-requests/notify.md",
      "link": "specs/external-requests/notify.md#req-notify-001-email-sending-endpoint",
      "hash": "<sha256-of-file>"
    }
  ]
}

Provider Notes

Use this skill when other commands request /ai-dev-kit:specs-find or spec traceability.
Prefer JSON for machine workflows; use TOON for compact prompt embedding.
Preserve ID/title casing; anchors should be lowercase + hyphenated.

Agent Skills: Spec Discovery Skill