Annotates agent prompts with structural XML tags for comprehension, gap detection, and skill extraction. Use when analyzing agent prompt structure, comparing agents across projects, or identifying reusable vs workflow-bound content in prompts.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Annotates agent prompts with structural XML tags for comprehension, gap detection, and skill extraction. Use when analyzing agent prompt structure, comparing agents across projects, or identifying reusable vs workflow-bound content in prompts.
license
MIT
metadata
{"author":"paw-project","version":"1.0"}
Agent Prompt Annotation Skill
Purpose
Annotations create a comprehension and authoring layer for agent prompts. They are NOT for runtime composition—they enable:
Structural vocabulary: Named categories for prompt sections
Explicit purpose: Each section declares what it IS
Gap detection: Verify expected structure exists
Cross-project comparison: Compare agents structurally, not just textually
Skill extraction: Identify reusable content vs workflow-bound content
> `<core-principles>`## Core Principles
>- `<guardrail scope="reusable">`**User value focus**: Describe WHAT & WHY, never implementation details
(no tech stack, file paths, library names, code snippets).
>- `</guardrail>`
>- `<guardrail scope="phase-bound">`**Spec completeness**: Every requirement must be testable. Include
acceptance criteria for each user story.
>- `</guardrail>`
>- `<decision-framework scope="reusable">`### When to Ask Clarifying Questions- Ambiguous requirements → Ask
- Missing context that blocks progress → Ask
- Stylistic preferences → Make reasonable choice, note it
>- `</decision-framework>`> `</core-principles>`
Anti-Patterns
❌ Over-Annotation
Don't tag every sentence. Tag meaningful sections:
Bad: 3 tags for a 2-line section
Good: 1 tag encompassing a coherent concept
❌ Forced Classification
Don't force content into a tag that doesn't fit:
Bad: Labeling prose as <guardrail> because it mentions "should"
Good: Using <guidance> or leaving untagged if ambiguous
❌ Premature Scope Assignment
Don't guess at scope if you're unsure:
Bad: scope="reusable" on everything that seems general
Good: Leave scope unspecified, refine after comparing across agents
❌ Annotation Without Understanding
Don't annotate mechanically:
Bad: Tagging based on keywords alone
Good: Understanding what the section DOES before choosing a tag
Outputs From Annotations
The visualization script (generate_viz.py) produces these outputs automatically:
Mindmap (Mermaid) (-mindmap.mmd): Topic hierarchy from annotation nesting
Markmap by Section (-by-section.mm.md): Interactive mindmap organized by document sections—preserves document structure
Markmap by Tag (-by-tag.mm.md): Interactive mindmap organized by tag type—shows fragmentation with ⚠️ warnings when same tag types appear in multiple sections
Flow Skeleton (-flow.mmd): Workflow steps + handoffs (refine with decisions)
Markmap is recommended for navigation—click nodes to collapse/expand branches, zoom and pan.
Fragmentation Detection
The summary includes a Fragmentation Analysis section that identifies when annotations of the same type (e.g., <guardrail>) are scattered across multiple document sections. This helps detect:
Redundant content: Similar rules stated in different places
Consolidation opportunities: Related content that could be grouped together
Structural issues: When document organization doesn't align with annotation taxonomy
Refined Flow: Add decision points and conditional edges to skeleton
Constraint Map: Which guardrails affect which workflow areas (requires reasoning)
Quick Reference
Tag Selection Flowchart
Is it about WHO the agent is?
→ <agent-identity>
Is it a rule that ALWAYS applies?
→ <guardrail>
Is it logic for making a CHOICE?
→ <decision-framework> or <classification-logic>
Is it a STEP in a sequence?
→ <workflow-step>
Is it a TEMPLATE for output?
→ <artifact-format>
Is it about COMMUNICATION style?
→ <communication-pattern>
Is it a CHECKLIST for completion?
→ <quality-gate>
Is it about WHAT HAPPENS NEXT?
→ <handoff-instruction>
Is it a CONCRETE EXAMPLE?
→ <example>
Scope Selection Flowchart
Could ANY agent use this?
YES → scope="reusable"
Is this about THIS PHASE's specific outputs/transitions?
YES → scope="phase-bound"
Does this control WORKFLOW orchestration?
YES → scope="workflow"
Uncertain?
→ Leave scope unspecified
