| name | sdl-author |
| description | Generate, repair, or review Solution Definition Language (SDL) v1.1 YAML from product requirements, architecture notes, repo discovery summaries, diagrams, or user descriptions. Use when Codex needs to create a valid `solution.sdl.yaml`, modular `.sdl.yaml` files, SDL fragments, schema-compliant fixes, assumptions, or review items for SDL authoring. |
SDL Author
Overview
Use this skill to turn architecture intent into valid SDL v1.1. Favor small, schema-valid SDL over comprehensive-looking YAML that invents facts.
Reference Loading
- If working in the
solution-definition-language repo, load reference/ai-authoring.md first. It is the compact machine reference.
- For deeper contract questions, load
spec/SDL-v1.1.md or reference/canonical-contract.md.
- If those repo files are unavailable, load
references/authoring-fast-path.md from this skill.
- For unclear input mapping, load
references/input-mapping.md.
Do not use stale README snippets, old .d.ts files, or legacy SDL examples as the source of truth.
Workflow
- Extract facts from the input.
- Identify product name, purpose, stage, architecture style, projects, database, auth, deployment, integrations, compliance, SLOs, and generated artifacts.
- Separate explicit facts from assumptions. Put uncertain details in review notes or
x-* metadata, not stable schema fields.
- Draft the minimum valid SDL first.
- Always include
sdlVersion, solution, architecture, and data.
- Add optional sections only when the input provides real facts or the user asks for a richer architecture baseline.
- Use canonical SDL v1.1 values exactly.
- Preserve enum casing and hyphenation, such as
MVP, modular-monolith, python-fastapi, and github-actions.
- Translate common aliases to canonical values before writing YAML.
- Avoid unsupported schema fields.
- Put custom metadata under
x-* extension fields.
- Do not invent non-
x-* root sections.
- Validate and repair.
- Run
scripts/validate-sdl.mjs <file> when a file exists.
- If validation fails, fix the SDL and validate again.
- Mention remaining warnings or assumptions in the final response.
Authoring Rules
- Prefer omit over guess. Missing optional sections are valid; unknown enum values are not.
- Do not set normalizer-inferred fields unless the input explicitly requires an override.
- If an optional section is present, include that section's required fields.
- Use
features[] as an array of objects. Do not group features by phase.
- Use
contracts.apis[], not a top-level contracts[].
- Use
slos.services[], not a top-level slos[].
- Use
auth.strategy: oidc with auth.sessions.accessToken: jwt when the input says JWT-based OIDC.
- Use
x-* keys for navigation patterns, UI notes, repo evidence, confidence, open questions, and source traceability.
Output Shape
When generating SDL for a user, provide:
- The SDL YAML or the path to the created SDL file.
- A short list of assumptions or review items.
- Validation result, including command run and any warnings.
When editing an existing SDL file, keep unrelated content intact and scope changes to the requested sections.
Validation Script
From this skill folder, use:
node scripts/validate-sdl.mjs path/to/solution.sdl.yaml
Useful options:
node scripts/validate-sdl.mjs path/to/solution.sdl.yaml --repo /path/to/solution-definition-language
node scripts/validate-sdl.mjs path/to/solution.sdl.yaml --json
The script looks for the SDL core package in the current repo and uses its parser, validator, semantic validator, resolver, and normalizer when available.