---
name: html-form-documenter
description: "Reference documentation for an existing HTML form that developers, QA, and product can share: purpose, a field-by-field table with types, constraints, and defaults, the validation rules, the submission contract, and a usage example. Use when an existing form needs a shared spec document with a field table, validation rules, and submission contract for developers, QA, and product to work from. Do not use for auditing the form for accessibility problems, or debugging why it fails to submit. Related topics: coding, html."
---

# HTML Form Documenter

Reference documentation for an existing HTML form that developers, QA, and product can share: purpose, a field-by-field table with types, constraints, and defaults, the validation rules, the submission contract, and a usage example.

## When to use

Use this skill when an existing form needs a shared spec document with a field table, validation rules, and submission contract for developers, QA, and product to work from. Do not use it for auditing the form for accessibility problems, or debugging why it fails to submit.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write the Overview: what the form collects, where and how it submits, and what success looks like.
3. Build the Fields table with label, name, type, required, default, constraints, and autocomplete token per control in source order.
4. State each validation rule in plain language with its user-facing message and who enforces it, when validation notes are on.
5. Add the audience-specific sections selected: submission contract, QA test matrix, UI states, or product summary.
6. Write the Example usage section with a filled submission and the resulting payload, then trim to the chosen style.

## Inputs

- **Form markup** (longer free text)
- **Documentation style** (choose one: Brief, Detailed, Technical, Friendly)
- **Include validation notes** (choose one: Yes, No)
- **Target audience** (choose any: Developers, QA, Designers, Product Managers)
- **Output format** (choose one: Markdown, HTML, Plain text)
- **Where it submits** (free text, e.g. "Endpoint and method if not visible in the markup")

## Output

A document in the chosen format with sections Overview, Fields (table), Validation when enabled, audience sections as selected, and Example usage, with no commentary outside the document.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### HTML Form Documenter

Document my form so engineering, QA, and product read the same spec.

#### Details
- Form markup: {{Form markup}}
- Documentation style: {{Documentation style}}
- Include validation notes: {{Include validation notes}}
- Target audience: {{Target audience}}
- Output format: {{Output format}}
- Where it submits: {{Where it submits}}

Write the Overview from the markup and the purpose it implies: what the form collects, where it submits, and what a successful submission results in. Build the Fields table with one row per control: label, name, type, required, default, constraints, and autocomplete token, in the order they appear. When validation notes are on, state each rule in plain language with the message the user sees, separating what the browser enforces from what the script or server must enforce. Shape the content for the audience: developers get the exact names and the submission contract (method, encoding, payload shape), QA get a test matrix of valid and invalid inputs per field, designers get the states (empty, error, disabled, success), and product gets the one-paragraph behaviour summary. Add an Example usage section showing a filled submission and the payload it produces. Match the style chosen: brief is one screen, technical includes the payload and error codes.

## Pitfalls

- Documenting the visible label but not the name attribute, which is the only identifier the backend and the tests use.
- Listing validation rules without the message the user sees, so QA cannot write the expected result.
- Describing the form as it should behave rather than as the markup actually behaves, which hides bugs in the spec.
