| name | Agent Spec Protocol — Reading Layer |
| description | Use this skill when the AI SEO agent is annotating a spec page's HTML with topic and kind attributes. Covers the AP reading layer — the structural mechanism that gives AI agents precise XPath addresses into page sections without reading the full document. Does not cover the AP pipeline layer (ap-gate, ap-gen, etc.) — spec pages are static HTML, not stateful pipeline documents. |
| version | 0.1.0 |
Agent Spec Protocol — Reading Layer for Spec Pages
The full AP spec lives at:
/home/rre/Work/mrgrampz-marketplace/agent-spec-protocol/skills/spec/SKILL.md
Read it for the complete protocol. This skill covers only what's relevant to spec pages: the reading layer.
What the reading layer is
AP's reading layer is two HTML attributes — topic and kind — that can be added to any existing HTML element without restructuring.
The analogy: you've written a long document with good answers in it. The AI SEO agent verified those answers are clean and extractable. But "extractable" still means the AI has to read the whole page to find them. The reading layer is the index: instead of reading 5,000 words to find the definition of a named concept, an AI issues one XPath query:
//*[@topic='ray-pattern'][@kind='definition']
And gets exactly that element. Nothing else in context. One query. One answer. The difference between reading a book and using its index.
Two attributes. That's the whole reading layer.
topic — what subject does this element cover?
User-defined, open vocabulary. Any lowercase kebab-case string. Groups elements by subject across the page.
<section topic="pipeline-overview" kind="overview">
For spec pages, use these topic naming conventions:
| Section type | Topic value |
|---|
| What this product/concept is | what-is-this |
| The problem it solves | problem |
| How it works (architecture) | how-it-works |
| Who built it / attribution | authorship |
| How it differs from alternatives | differentiation |
| Named concept being defined | [concept-name-kebab] |
| Key components or agents | [component-name] |
| How to get or use it | getting-started |
| Stats or specific metrics | metrics |
| Pricing or availability | availability |
Multiple elements can share the same topic — they cover the same subject at different levels of detail.
kind — what type of content is this?
Closed vocabulary — AP defines these values and they mean the same thing on any AP document:
| Value | Meaning | When to use |
|---|
summary | A condensed version of larger content | The one-line answer. Highest-priority content for AI extraction. |
overview | High-level introduction | First substantive paragraph introducing a topic. |
reference | Detailed lookup material | Tables, specs, detailed agent descriptions. |
key-point | A single critical insight | The core argument, the differentiating claim. |
definition | A term and its meaning | First mention of any named concept. |
example | A concrete illustration | Code examples, pipeline diagrams, concrete scenarios. |
instruction | Step-by-step directions | How to run, how to configure, how to deploy. |
How to annotate a spec page
Add topic and kind to the elements that already contain your answer-dense content. Do not restructure the page. Do not add new elements. Just add attributes to what's already there.
Hero / intro section
<p topic="what-is-this" kind="definition">
The Spec Page Agentic Team is a Claude Code plugin that takes any idea, brief, or URL as input
and produces a complete, deployed HTML spec page — built on The Point CSS framework, reviewed
for code quality, and optimized for both traditional SEO and AI discoverability.
</p>
<p topic="what-is-this" kind="summary">
One command. Seven agents. A live page at the end.
</p>
Named concepts
Every named concept the page introduces gets a definition annotation on its first clear, one-sentence definition:
<p topic="ray-pattern" kind="definition">
The Ray Pattern is an agent pipeline architecture where a single discovery interface routes
to specialized sub-agents, each with one job — the interface is stable regardless of how
many specialists run beneath it.
</p>
Attribution
<p topic="authorship" kind="key-point">
Built by <a href="https://robertrevans.com">Robert Evans</a>.
</p>
How it works
<section topic="how-it-works" kind="overview">
<p>The pipeline runs seven specialized agents in sequence...</p>
</section>
Problem statement
<p topic="problem" kind="key-point">
Every new spec page is a hand-crafted one-off. The result is inconsistent quality,
inconsistent SEO, and zero AI discoverability.
</p>
What NOT to annotate
- Decorative elements (nav, footer decorations, dividers)
- Elements whose content is already captured in a better-targeted element with the same topic/kind
- Every element on the page — annotate selectively. An index with 40 entries is worse than one with 7.
The rule: if an AI agent querying for topic='what-is-this' kind='summary' should get this element, annotate it. If not, don't.
After annotating: verify with XPath
After adding annotations, verify the key queries return the right elements:
| Query | Should return |
|---|
//*[@topic='what-is-this'][@kind='definition'] | The one-sentence definition of the product |
//*[@topic='what-is-this'][@kind='summary'] | The one-line value statement |
//*[@topic='authorship'][@kind='key-point'] | The Robert Evans attribution element |
//*[@topic='problem'][@kind='key-point'] | The problem statement |
//*[@kind='definition'] | All named concept definitions on the page |
If any query returns nothing or returns the wrong element, the annotation is incomplete.
Relationship to AI SEO
The AI SEO agent runs the answer density check (Check 2) — it identifies which paragraphs answer the key questions. AP annotation is the structural completion of that work: once you know WHERE the answers are, add topic and kind so AI agents can find them without reading the whole page.
The sequence is always:
- AI SEO ensures the answer exists as a clean, extractable paragraph
- AP annotates that paragraph so it has a stable machine address
Never annotate before optimizing. An extractable answer with a machine address beats both in isolation.
