| name | ap-validate |
| description | Validates an HTML file against the Agent Spec Protocol. Reads the file, runs every rule in the validation checklist, and returns a structured pass/fail report with XPath locations for every violation. |
AP Validate Skill
Validates an HTML file against the Agent Spec Protocol v1.0 spec.
Read the full spec first: agent-spec-protocol skill.
Input
An HTML file path. Read the full file before beginning.
Process
Run every rule in the validation checklist. For each violation, record:
- Rule that failed
- XPath location of the violating element (e.g.,
//section[3][@id='competitive'])
- What was found vs. what was required
Output Format
Return a structured report:
AP Validation Report
File: [path]
Result: PASS | FAIL
Violations ([n]):
[xpath] — [rule] — found "[value]", expected [expected]
Warnings ([n]):
[xpath] — [advisory note]
Summary:
[n] sections checked
[n] required attributes verified
[n] dependency chains verified
If zero violations: Result: PASS. If any violation: Result: FAIL.
Validation Rules (run all)
Structure Rules
S1 — Valid HTML5: document must have <!DOCTYPE html>, <html>, <head>, <body>
S2 — Clean <html> element: <html> must not have any data-ap-* attributes
- XPath to check:
//html[@*[starts-with(name(),'data-ap-')]]
- Violation: list every
data-ap-* attribute found on <html>
S3 — Head metadata present: <head> must contain at least one <meta> with name attribute containing a colon (namespaced)
- XPath to check:
//head/meta[contains(@name,':')]
- Violation if count = 0
Section Rules
SE1 — Element type: every AP section must be <section>, identified by presence of id starting with ap-
- XPath to find AP sections:
//*[@id[starts-with(.,'ap-')]]
- For each: verify element name is
section
SE2 — Required attributes: every AP section must have id, data-ap-agent, data-ap-stage, data-ap-status
- For each
<section id="ap-*">: check all four are present and non-empty
SE3 — ID format: all AP section IDs must match ^ap-[a-z][a-z0-9-]*$
- Reject: uppercase letters, underscores, digits immediately after
ap-
SE4 — ID uniqueness: no two elements share the same id value
SE5 — Status vocabulary: data-ap-status must be one of:
pending, running, passed, failed, skipped, blocked
SE6 — Gate vocabulary: data-ap-gate (if present) must be one of:
required, optional, none
SE7 — Format vocabulary: data-ap-format (if present) must be one of:
prose, json, list, table, html, mixed
SE8 — Mutable vocabulary: data-ap-mutable (if present) must be one of:
agent, human, false
SE9 — Stage is integer: data-ap-stage must be a positive integer string (/^[1-9][0-9]*$/)
SE10 — Stage uniqueness: no two AP sections share the same data-ap-stage value
Dependency Rules
D1 — Depends-on references: every ID in data-ap-depends-on (space-separated) must match an existing id in the document
D2 — Context references: every ID in data-ap-context (space-separated) must match an existing id in the document
D3 — No circular dependencies: for each section with data-ap-depends-on, trace the dependency chain — no section may eventually depend on itself
Class Rules
C1 — No ap-* visual styling: ap-* classes are behavioral flags only. Flag a warning (not a violation) if an ap-* class is also targeted by a <style> block with non-layout CSS properties (color, font, background, border, etc.)
C2 — Advisory: sections with data-ap-mutable="false" should carry class ap-source-of-truth
