Agent-Skills.md

Agent Skills: bootstrapping-design-docs

Creates design document infrastructure including templates, workflows, and a specific design doc skill. Use when setting up design docs for a new project or when the user mentions "bootstrapping-design-docs".

UncategorizedID: SteveBronder/skillrena/bootstrapping-design-docs

Repository

SteveBronder/skillrena
SteveBronder
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/SteveBronder/skillrena/tree/HEAD/skillrena/bootstrapping-design-docs

Skill Files

Browse the full folder contents for bootstrapping-design-docs.

Download Skill

Loading file tree…

skillrena/bootstrapping-design-docs/SKILL.md

Skill Metadata

Name
bootstrapping-design-docs
Description
Creates design document infrastructure including templates, workflows, and a specific design doc skill. Use when setting up design docs for a new project or when the user mentions "bootstrapping-design-docs".
<NOTE> Use the $activate-memories skill if you have not already to get an overview of the project before proceeding. </NOTE> <objective> 1. If the `design-docs` folder does not already exist, create a repo-local `design-docs/` workspace (templates + active docs + index). - If the `design-docs` folder already exists, stop and ask the user how to proceed. 2. Create a **project-specific** design doc template. If the user does not specify a specific type of design doc they want to create, we will be creating a general design document template called `base-design-doc.md` for the overall project. 3. Generate a **project-specific** design-doc skill for authoring design docs with: - explicit specs (interfaces, signatures, types) - mandatory test-data acquisition plan for ETL / HTTP / WebSocket work - enforceable guardrails against common agent failure modes - Example: The user wants to make a design doc skill for the ETL pipeline creations in the project. Then your task would be to create a `$etl-design-doc` skill. 4. Support repeated runs to create additional templates (variants) without breaking existing docs.

For the rest of this document {DESIGN_DOC_SKILL_NAME} will refer to the name of the skill we will make that will later be used to generate design docs for this project. Default: creating-design-doc. Once you create the base design doc template and skill, you must ask questions to the user to help clarify anything you are unsure of. This is a joint user-agent process: ask targeted questions when unsure; do not finalize templates without user review. </objective>

<outputs> Create (idempotent; do not overwrite without preserving history):

<file_list>

  • design-docs/README.md - How design docs are written, reviewed, and used for delegated execution.
  • design-docs/active/ - Directory for active design documents.
  • design-docs/agents/ - Directory for agent-executable XML subtasks.
  • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/SKILL.md - The generated ${DESIGN_DOC_SKILL_NAME} skill.
  • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md - Lists available templates and when to use them.
  • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/base.md - Meta "base" design doc template (guardrails + structure).
  • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/<variant>.md - Project-specific templates (e.g., etl-pipeline.md, feature.md). </file_list>

Note: Templates are bundled with the skill (not in design-docs/) per Agent Skills progressive disclosure pattern.

<output_format> Design docs are written in markdown - not XML. Markdown is easier for humans to read/edit and for agents to parse during collaboration. Agent-executable subtasks use XML in a separate file under design-docs/agents/. </output_format>

<agent_name_resolution> Replace {AGENT_NAME} with the agent's config directory:

  • .aider/ - Aider
  • .claude/ - Claude Code
  • .codex/ - OpenAI Codex CLI
  • .copilot/ - GitHub Copilot
  • .cursor/ - Cursor

If the repo has an existing agent config directory, use it. If multiple exist, prefer the current agent's. If none exist, create one. </agent_name_resolution> </outputs>

<preconditions> Before asking questions, scan the repo to ground defaults: If you have not already, run the $activating-memories skill to get an overview of the project. <scan_targets> 1. **Languages/frameworks/build files** 2. **CI entrypoints** 3. **Project Specific Utility modules** 4. **DB/migrations** 5. **Style rules** </scan_targets> </preconditions>

<generation_steps>

  1. Create folder structure (if missing):

    • design-docs/
    • design-docs/active/
    • design-docs/agents/
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/

  2. Write design doc skill and bundled templates:

    • design-docs/README.md (workflow + approvals)
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/SKILL.md (the skill)
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md (template index)
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/base.md (meta template with guardrails)
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/skill.md (skill creation template)
    • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/feature.md (feature template)

  3. Run Adaptive Questioning Protocol:

    • Produce "Detected Defaults Summary"
    • Ask triggered questions
    • Stop for answers before proceeding

  4. Idempotency:

    • Never overwrite existing templates without timestamped backup
    • Add new variants to .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md </generation_steps>

<questioning_protocol> Ask only questions that materially influence template contents.

<question_tags> Every question must be tagged:

  • [blocking] - must be answered to generate correct template or enforce safety
  • [important] - significantly improves template quality / reduces future rework
  • [optional] - preference-level; safe defaults exist </question_tags>

<question_budget>

  • Max 10 questions total.
  • Each question includes a one-line "why" tying to a template section, guardrail, or convention. </question_budget>

<triggered_questions> Ask only what applies based on scan:

  • Migrations tooling detected -> ask DB reset/backfill/rollback/testing policy
  • HTTP/WS dependencies detected -> ask record/replay + fixture storage constraints
  • Monorepo structure detected -> ask where templates live and how commands differ
  • No tests/CI detected -> ask what canonical verification commands should be </triggered_questions>

<template_delta_preview> Before writing files, show:

  • Which variants will be created
  • Repo-specific defaults that will be baked in
  • Any tightened guardrails derived from project norms
  • Any unresolved [blocking] items

Stop and ask for [blocking] answers before proceeding. </template_delta_preview> </questioning_protocol>

<common_questions> Ask only what you cannot infer from the scan: <question_examples>

  1. [blocking] Template variants desired

    • "Which templates do you want generated? (e.g., feature, etl_http_ws, db_migration, refactor)"
    • Why: determines templates bundled with skill.

  2. [blocking] Test integrity policy

    • "What is your rule on mocks? (only mock boundaries; prefer record/replay; never mock core transforms)"
    • Why: populates guardrails + testing strategy.

  3. [blocking] Data capture constraints

    • "Can we store captured payloads under tests/fixtures/? Any size/licensing/PII constraints?"
    • Why: populates test-data acquisition plan.

  4. [blocking] Destructive actions boundary

    • "What DB reset patterns are allowed in tests? (transactions/temp schema/containers). Forbidden actions?"
    • Why: prevents unsafe "delete DB to pass tests" behavior.

  5. [important] Type discipline

    • "For Python projects, what is your stance on Optional/None? (forbid unless justified; require invalid states unrepresentable)"
    • Why: shapes interface-contract requirements.

  6. [important] Review workflow

    • "Stop at Template Delta Preview for approval, or write files and you review diffs?"
    • Why: controls collaboration checkpoint. </question_examples> </common_questions>

<base_template_sections> The base template MUST include these sections (in order):

  1. Identity and lifecycle
  2. Context
  3. Problem
  4. Goals / Non-goals
  5. Requirements (FRs / NFRs)
  6. Constraints and invariants (include DB + test integrity)
  7. Proposed design (architecture, contracts, schemas, idempotency/retries)
  8. Project common utilities that will be used.
  9. Project common utilities that will be created.
  10. Interface contracts (explicit signatures; Optional/None justification required)
  11. Alternatives considered (>=2)
  12. Test data acquisition plan (mandatory for external I/O / ETL)
  13. Testing and verification strategy (commands + CI gates + test integrity rules)
  14. Rollout / migration / ops (flags, backfills, observability, runbook)
  15. Open questions / follow-ups
  16. Subtasks (human-readable checklist for review)

Subtasks Section Format:

## Subtasks

### T1: [Task Title]
- **Summary**: One sentence objective
- **Scope**: What's in / what's out
- **Acceptance**: Binary pass/fail criteria
- **Status**: [ ] Not started / [~] In progress / [x] Complete

### T2: [Task Title]
...

</base_template_sections>

<guardrails> Include verbatim in the design doc skill you create under "Engineering Guardrails for Agent Execution":
  • Reuse-first rule (anti-duplication): search existing utilities; record decision per task.
  • No destructive shortcuts: never delete dev/prod data to pass tests; destructive actions require confirmation.
  • Test integrity (anti-mock-cheating): mock boundaries only; prefer record/replay; do not change tests without spec change approval.
  • Signature discipline (anti-vagueness): explicit types/invariants; Optional/None requires justification and handling strategy.
  • Alternatives requirement: evaluate >=2 alternatives + "do nothing".
  • Uncertainty protocol: ask [blocking] questions when unsure; do not proceed. </guardrails>

<completion_criteria>

  • design-docs/ exists with README + active/ + agents/ subdirectories
  • name of ${DESIGN_DOC_SKILL_NAME} confirmed with user.
  • ${DESIGN_DOC_SKILL_NAME} skill exists at .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/
  • Templates bundled at .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/
  • base.md includes guardrails and human-readable subtasks section format
  • At least one project-specific template variant exists with repo-specific test commands
  • Skill workflow: human-readable subtasks in main doc -> user approval -> XML in design-docs/agents/ </completion_criteria>

<decision_points>

  • No existing config directory -> create one for current agent
  • Multiple templates requested -> generate each as separate variant file
  • User wants immediate write vs preview -> honor preference from question 6 </decision_points>

<failure_modes>

  • Scan finds nothing -> ask user for stack/commands explicitly
  • Conflicting conventions -> note in template as "resolve before use"
  • Overwriting existing templates -> create backup with timestamp first </failure_modes>