Parse specs to extract IDs, titles, and traceability metadata (repo, path, hash).
spec-discovery follows the SKILL.md standard. Use the install command to add it to your agent stack.
---
name: spec-discovery
description: "Parse specs to extract IDs, titles, and traceability metadata (repo, path, hash)."
---
# 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)
1. **Load repositories**: ROOT + EXTRA_REPOS
2. **Walk specs**: `specs/`, `specs/external-requests/`, skip `specs/templates/`
3. **Parse headings**: match `^#+\s*(REQ-[A-Za-z0-9_-]+)\s*:?\s*(.*)$`
4. **Normalize**: path relative to repo root, anchor from ID + title
5. **Traceability**: compute SHA-256 of file content; record `source_repo`, `path`, `hash`
6. **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
```json
{
"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.