Structured Spec

What it does

When your agent uses it

• Check completeness/traceability of a spec
• Requirements doc
• Decision record
• Migrate a plain-Markdown spec to this format

Example prompts

• “/structured-spec”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1Define milestones in frontmatter: milestones: [{name: "Phase 1: Core", target_date: "2026-09-01", status: "in-progress"}, ...]
2. 2Tag annotations with milestone: "Phase 1: Core" — requirements, contracts, tests, and tasks
3. 3Review per phase — completeness rules (§6.5) apply per milestone. Phase 2 requirements don't block Phase 1 approval.
4. 4Slice by milestone — orchestrators can dispatch Phase 1 tasks first, then Phase 2 after review

What it can do on your machine

Read from SKILL.md and the folder at commit 9e997ba. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Structured Spec loads about 2.3k tokens when it runs. Until then it costs about 171 tokens; SKILL.md has 870 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~171

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from irahardianto/awesome-agv at commit 9e997ba, republished under its MIT licence (© irahardianto). 870 words, ~2,301 tokens.

name

structured-spec

description

Write, review, validate, or parse structured specification documents — PRDs, SDDs (design docs), implementation plans, TSDs (technical specs), BDD specs, and ADRs (architecture decision records) — using the Structured Spec standard (YAML frontmatter + Markdown narrative + HTML-comment annotations for requirement/contract/test/architecture/decision/slo + executable code contracts, with requirement-to-contract-to-test traceability). Use when asked to draft, scaffold, template, or check completeness/traceability of a spec, requirements doc, design doc, or decision record, migrate a plain-Markdown spec to this format, or slice a spec into tasks for multiple agents.

docs/
├── specs/                    ← PRDs, SDDs, TSDs, BDD specs, Implementation Plans
│   ├── prd-billing-export.md
│   ├── sdd-payment-service.md
│   ├── tsd-billing-api.md
│   ├── bdd-checkout-flow.md
│   └── plan-v2-migration.md
├── decisions/                ← ADRs (convention from `adr` skill)
│   ├── 0001-use-postgresql.md
│   └── 0002-adopt-feature-structure.md
├── research_logs/            ← Research findings (convention from `research-methodology` skill)
├── audits/                   ← Audit reports (convention from `code-review` skill)
└── debugging/                ← Debug investigations (convention from `debugging-protocol` skill)

---
$schema: "https://raw.githubusercontent.com/irahardianto/awesome-agv/main/.agents/skills/structured-spec/spec-schema.json"
spec_id: "PRD-BILLING-EXPORT-V1"
title: "Billing Export"
doc_type: "prd"
status: "draft"
version: "0.1.0"
owners: ["platform-team"]
created: "2026-08-18"
modified: "2026-08-18"
---

# 1. Problem Context

Finance reconciles invoices by hand because usage data never leaves the platform.

<!-- requirement
  id: REQ-001
  title: Export daily usage as CSV
  priority: must
  category: functional
  rationale: Manual reconciliation costs the finance team two days per month
-->

Exports run nightly and cover the previous UTC day.

<!-- contract
  id: CT-API-001
  type: api-contract
  title: Usage export endpoint
  stack_category: application-code
  implements_requirements: [REQ-001]
-->

```yaml
paths:
  /exports/usage:
    get:
      parameters: [{ name: date, in: query, required: true, schema: { type: string, format: date } }]
      responses: { "200": { description: CSV export } }
```

<!-- test
  id: TC-001
  type: acceptance-test
  title: Export returns the previous day's usage
  verifies_requirements: [REQ-001]
-->

```gherkin
Scenario: Export returns the previous day's usage
  Given usage exists for 2026-08-17
  When the client requests the export for 2026-08-17
  Then the response is CSV containing that day's rows
```

© irahardianto, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 11 other files in .agents/skills/structured-spec of irahardianto/awesome-agv.

• SKILL.md
• example-prd.md
• profiles/adr.md
• profiles/bdd.md
• profiles/implementation-plan.md
• profiles/prd.md
• profiles/sdd.md
• profiles/tsd.md
• spec-schema.json
• specification.md
• taxonomy.md
• template.md

Open the folder on GitHubat commit 9e997ba