generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/create-hld
create-hld
VerifiedInvoke to author a High-Level Design (HLD) at discovery / prototyping phase. Design-only: delivers intent + spec for AI and humans to build against — no implementation plan, no code outside examples/. Trigger keywords: "HLD", "high level design", "design doc", "architecture design", "create a design". Also triggers on /create-hld.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 2.4 KB |
| SKILL.md | skill md | 6.5 KB |
| agents/openai.yaml | config | 360 B |
| assets/AGENTS.template.md | markdown | 1.3 KB |
| assets/LADR.template.md | markdown | 1.1 KB |
| assets/NFR.template.md | markdown | 1.1 KB |
| assets/README.template.md | markdown | 2.1 KB |
| assets/c4-context.template.md | markdown | 2.0 KB |
| assets/examples.README.template.md | markdown | 505 B |
| references/diagram-selection.md | markdown | 2.2 KB |
| references/status-vocabulary.md | markdown | 1.6 KB |
| scripts/hld-agents-rules.shexecutable | script | 3.3 KB |
| scripts/scaffold-hld.shexecutable | script | 4.7 KB |
SKILL.md
View on GitHub---
name: create-hld
description: >
Invoke to author a High-Level Design (HLD) at discovery / prototyping phase.
Design-only: delivers intent + spec for AI and humans to build against — no
implementation plan, no code outside examples/. Trigger keywords: "HLD",
"high level design", "design doc", "architecture design", "create a design".
Also triggers on /create-hld.
allowed-tools: >
Bash(.agents/skills/create-hld/scripts/scaffold-hld.sh:*),
Bash(.agents/skills/create-hld/scripts/hld-agents-rules.sh:*),
Read, Write, Edit
models:
claude: opus # high-complexity; multi-step clarification gates + architectural judgment
copilot: auto
codex: gpt-5.5
---
# Create HLD — High-Level Design authoring
## TL;DR
Produce a `docs/hlds/NNN-<slug>/` folder that captures **intent + spec** for a design at
discovery/prototyping phase. The HLD says *what* we are building, *why*, the decisions behind
it (LADRs), the quality bar it must meet (NFRs), and its architecture (diagrams). It does
**not** say *how to build it* — no implementation plan, no phasing, no code (except an optional
`examples/` folder). This skill is the source of truth for HLD structure in this repo.
## Non-Negotiables
- **Design only.** No implementation plan, no execution phasing/sequencing, no sub-issue
breakdown — that lives in the issue/work tracker. The HLD is for discovery/prototyping.
- **No code** anywhere except `examples/`. README, LADRs, NFRs, and AGENTS.md are code-free.
- **AGENTS.md has no architecture section.** Architecture lives in `diagrams/`. The HLD
AGENTS.md follows `scripts/hld-agents-rules.sh`, which deliberately omits System Context.
- **C1 is the floor, not the ceiling.** Always produce a C4Context. Investigate the design and
*recommend* further diagrams (`references/diagram-selection.md`); do not pad by default.
- **Clarify before inventing.** Initiative name, goals, constraints, stakeholders, target
system — ask, do not assume (Phase 1 of the AI workflow rules).
- **Every NFR is measurable + verifiable.** Vague NFRs ("fast", "reliable") are forbidden.
- **Every LADR and NFR is one file** — a horizontal concern spanning the vertical HLD.
## Invocation
`/create-hld <kebab-slug>` — or describe the design in natural language and follow the workflow.
## Output structure (the contract)
```
docs/hlds/NNN-<kebab-slug>/
├── README.md # human entry point: intent + spec (no impl, no code)
├── AGENTS.md # AI-coder guardrails — NO architecture/System-Context section
├── diagrams/
│ └── c4-context.md # C1 System Context (mandatory) + AI-recommended diagrams
├── ladrs/
│ └── LADR-NN-<slug>.md # one decision per file
├── nfrs/
│ └── NFR-NN-<attribute>.md # one quality attribute per file
└── examples/ # OPTIONAL — the only place code may appear
```
- `NNN` is 3-digit, zero-padded, next-available — the scaffold script computes it.
- `AGENTS.md` is plain-named (root of the HLD folder); the `load-agents-context` hook still
auto-loads it. It is guardrails, not narrative.
- File shapes are defined by the templates in `assets/`; the scaffold script seeds them.
## Workflow
1. **Clarify scope** — initiative name, the problem and target outcome, key goals, hard
constraints, stakeholders, the target system and its external dependencies. Do not invent.
2. **Scaffold** — run:
```bash
.agents/skills/create-hld/scripts/scaffold-hld.sh <slug> [--title "Title"] [--examples]
```
It prints JSON of the created paths. Add `--examples` only if code samples will help.
3. **Draft README.md** — Intent, Key Goals (each with **acceptance criteria / DoD**), Core
Separation of Concerns (blockquoted thesis), Guiding Principle. Get the thesis and goals
signed off before writing decisions. No rollout/phasing section, no risks section.
4. **Draft strategic LADRs** (`ladrs/LADR-01..N`) — one architectural decision each, derived
from the goals. Default status **Draft** (discovery). One file per decision.
5. **Investigate and recommend diagrams** — C1 is mandatory. Using
`references/diagram-selection.md`, decide whether container / flow / sequence / ER / class
diagrams add understanding. **Surface the recommendation to the user with a one-line
rationale per diagram before writing them.** Then write into `diagrams/`.
6. **Draft NFRs** (`nfrs/NFR-01..M`) — one quality attribute per file: measurable Requirement,
Verification mechanism, Acceptance Criteria, Applies-To. Reference them from the README NFR table.
7. **Draft tactical LADRs** if any *how* decisions surfaced (runtime, protocol, config). Number
after the strategic ones; never renumber.
8. **Draft AGENTS.md** — apply `scripts/hld-agents-rules.sh`. Derive Non-Negotiables from the
LADRs, fill the decisions and NFR pointer tables. No architecture section.
9. **Wire the tables** — README LADR table and NFR table list every file with status.
To read the AGENTS.md rules at any point (agent-agnostic, no hook needed):
```bash
.agents/skills/create-hld/scripts/hld-agents-rules.sh
```
## Quality bar before marking ready
- [ ] Every Key Goal has acceptance criteria / DoD.
- [ ] Every LADR has Context, Decision, Consequences (Alternatives recommended).
- [ ] Every NFR has a measurable target AND a verification mechanism AND acceptance criteria.
- [ ] C1 diagram present; every extra diagram is justified and one-concern.
- [ ] AGENTS.md has no architecture section, no code, no impl/phasing.
- [ ] No code outside `examples/`.
- [ ] Mermaid renders (no syntax errors).
- [ ] All cross-links are relative and resolve. No `[TODO]`; use `TBD` with owner/trigger.
## Agent-agnostic notes
- Scripts are `bash` + coreutils only; no Claude-specific behaviour.
- The AGENTS.md quality rules ship inside the skill (`scripts/hld-agents-rules.sh` + the
summary above), so Codex / Copilot / Cursor — which do not run Claude Code hooks — are fully
self-contained. The repo's global `knowledge-rule-enforce.sh` hook is unaffected and still
governs general (non-HLD) AGENTS.md files.
## References
- `references/status-vocabulary.md` — Draft / Prototype / Accepted lifecycle; strategic vs tactical.
- `references/diagram-selection.md` — when to add each diagram type beyond C1.
## Changelog
| Date | Change | Ref |
| :---- | :---- | :---- |
| 2026-07-23 | Corrected the HLD scaffold contract to the visible `docs/hlds/` tree. | #253 |
| 2026-06-16 | Created — design-only HLD skill, made project-agnostic for the smooth-devex template. | — |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |