fix: documentation category cleanup

skills/documentation/agent-memory/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: agent-memory
 name: Agent Memory
-description: Step-by-step guidance for agent memory.
+description: Structure agent memory docs so context stays discoverable, bounded, and maintainable without implying hidden system state.
 category: Documentation
+requires: []
+examples:
+  - "Design agent memory docs so important context stays discoverable and appropriately scoped."
+  - "Review agent memory docs for taxonomy gaps, retrieval friction, and freshness risk."
 ---
 
 # Agent Memory
 
-Support agent memory workflows with clear steps and best practices.
+Use this skill when the user needs agent memory docs organized so important context can be captured, found, and updated without implying hidden memory or invisible indexed state.
 
-## When to Use
+## Start By Clarifying
+- What information deserves durable capture versus short-lived discussion.
+- How readers should locate the right context later.
+- Which taxonomy, tags, or summary conventions will keep retrieval manageable.
+- What freshness signals or ownership rules prevent silent decay.
+- Where the boundaries are between documented knowledge and inferred context.
 
-- You need help with agent memory.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the knowledge objects, categories, and retrieval paths readers will use.
+2. Choose a structure for summaries, tags, links, and source references.
+3. Document what should be captured, what should be omitted, and how updates happen.
+4. Add examples of good entries, summaries, or indexing conventions.
+5. Review for taxonomy sprawl, stale knowledge, and unclear source-of-truth rules.
 
-## Output
+## Good Output
+- Knowledge structure or taxonomy recommendation.
+- Rules for summaries, tags, references, and freshness.
+- Ambiguities where context capture could become misleading or too broad.
+- Maintenance guidance so the knowledge system stays usable.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Documenting everything and creating an unsearchable memory dump.
+- Using vague labels that do not help future retrieval.
+- Failing to separate verified facts from interpretation or working notes.
+- Implying persistent memory or indexing capabilities that are not actually present.
+
+## Boundaries
+- Do not imply undocumented retrieval or memory systems exist.
+- Prefer explicit taxonomy and source references over invisible context magic.

skills/documentation/ai-context/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: ai-context
 name: AI Context
-description: Step-by-step guidance for AI context.
+description: Structure AI context docs so context stays discoverable, bounded, and maintainable without implying hidden system state.
 category: Documentation
+requires: []
+examples:
+  - "Design AI context docs so important context stays discoverable and appropriately scoped."
+  - "Review AI context docs for taxonomy gaps, retrieval friction, and freshness risk."
 ---
 
 # AI Context
 
-Support ai context workflows with clear steps and best practices.
+Use this skill when the user needs AI context docs organized so important context can be captured, found, and updated without implying hidden memory or invisible indexed state.
 
-## When to Use
+## Start By Clarifying
+- What information deserves durable capture versus short-lived discussion.
+- How readers should locate the right context later.
+- Which taxonomy, tags, or summary conventions will keep retrieval manageable.
+- What freshness signals or ownership rules prevent silent decay.
+- Where the boundaries are between documented knowledge and inferred context.
 
-- You need help with ai context.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the knowledge objects, categories, and retrieval paths readers will use.
+2. Choose a structure for summaries, tags, links, and source references.
+3. Document what should be captured, what should be omitted, and how updates happen.
+4. Add examples of good entries, summaries, or indexing conventions.
+5. Review for taxonomy sprawl, stale knowledge, and unclear source-of-truth rules.
 
-## Output
+## Good Output
+- Knowledge structure or taxonomy recommendation.
+- Rules for summaries, tags, references, and freshness.
+- Ambiguities where context capture could become misleading or too broad.
+- Maintenance guidance so the knowledge system stays usable.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Documenting everything and creating an unsearchable memory dump.
+- Using vague labels that do not help future retrieval.
+- Failing to separate verified facts from interpretation or working notes.
+- Implying persistent memory or indexing capabilities that are not actually present.
+
+## Boundaries
+- Do not imply undocumented retrieval or memory systems exist.
+- Prefer explicit taxonomy and source references over invisible context magic.

skills/documentation/api-design/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: api-design
 name: API Design
-description: Step-by-step guidance for API design.
+description: Document API design docs with clear responsibilities, decision points, sequencing, and follow-through expectations.
 category: Documentation
+requires: []
+examples:
+  - "Document API design docs so contributors know the flow, roles, and exit criteria."
+  - "Turn this loose workflow into API design docs with checkpoints, ownership, and review gates."
 ---
 
 # API Design
 
-Support api design workflows with clear steps and best practices.
+Use this skill when the user needs API design docs that turn an informal workflow into something reviewable, teachable, and easier to execute consistently.
 
-## When to Use
+## Start By Clarifying
+- Who participates in the process and where responsibilities change hands.
+- What the entry criteria, checkpoints, and exit criteria should be.
+- Which decisions require sign-off, escalation, or documented rationale.
+- What artifacts, links, or evidence should exist at each stage.
+- How the process should stay lightweight enough to be followed in practice.
 
-- You need help with api design.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the objective of the process and the scenarios it is meant to cover.
+2. Map the stages, decision points, owners, and required artifacts.
+3. Make review gates, success criteria, and escalation rules explicit.
+4. Add examples, templates, or checklists where teams commonly drift.
+5. Document how the process is maintained when the system or team changes.
 
-## Output
+## Good Output
+- Process outline with roles, sequence, and decision gates.
+- Required artifacts, examples, or checklists.
+- Open questions or edge cases that need policy rather than improvisation.
+- Maintenance notes so the process stays current.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Describing the ideal path but omitting ownership and exception handling.
+- Adding heavy ceremony without clear value or decision support.
+- Failing to show what done looks like at each stage.
+- Letting the process drift from how teams actually work.
+
+## Boundaries
+- Do not confuse process guidance with proof that the process is already being followed.
+- Prefer concrete responsibilities and exit criteria over vague workflow prose.

skills/documentation/api-documentation-generator/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: api-documentation-generator
 name: API Documentation Generator
-description: Step-by-step guidance for API documentation.
+description: Create and maintain API reference docs with accurate contracts, examples, edge cases, and version-aware detail.
 category: Documentation
+requires: []
+examples:
+  - "Create API reference docs with examples, constraints, and edge-case coverage."
+  - "Review API reference docs for gaps in contracts, parameters, compatibility notes, or failure cases."
 ---
 
 # API Documentation Generator
 
-Support api documentation workflows with clear steps and best practices.
+Use this skill when the user needs API reference docs that readers can trust as a durable lookup source rather than a vague narrative summary.
 
-## When to Use
+## Start By Clarifying
+- What entities, endpoints, fields, functions, or concepts are actually in scope.
+- Which versions, compatibility boundaries, or deprecations matter.
+- What inputs, outputs, defaults, and error cases readers most often misunderstand.
+- Which examples are necessary to make the reference usable, not just complete.
+- What surrounding guide material should be linked rather than duplicated.
 
-- You need help with api documentation generator.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the reference surface and group it into durable reader-facing sections.
+2. Document contracts, required fields, defaults, side effects, and failure modes explicitly.
+3. Add examples that show normal use, edge cases, and compatibility caveats.
+4. Call out version boundaries, deprecations, and non-obvious constraints.
+5. Review for omissions that would force readers back into code or guesswork.
 
-## Output
+## Good Output
+- Reference structure by resource, concept, or API surface.
+- Missing contract details, examples, or compatibility notes.
+- Places where defaults, limits, or failure behavior need stronger explanation.
+- Cross-links needed to connect reference material to task-oriented guides.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Documenting names without documenting behavior or constraints.
+- Skipping error cases because the happy path feels sufficient.
+- Hiding version-specific caveats until readers hit production issues.
+- Letting the reference drift from actual source behavior.
+
+## Boundaries
+- Do not imply undocumented behavior is guaranteed.
+- Prefer precise contracts and examples over broad marketing-style wording.

skills/documentation/architecture-decision-records/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: architecture-decision-records
 name: Architecture Decision Records
-description: Step-by-step guidance for architecture decision records.
+description: Document architecture decision records with clear responsibilities, decision points, sequencing, and follow-through expectations.
 category: Documentation
+requires: []
+examples:
+  - "Document architecture decision records so contributors know the flow, roles, and exit criteria."
+  - "Turn this loose workflow into architecture decision records with checkpoints, ownership, and review gates."
 ---
 
 # Architecture Decision Records
 
-Support architecture decision records workflows with clear steps and best practices.
+Use this skill when the user needs architecture decision records that turn an informal workflow into something reviewable, teachable, and easier to execute consistently.
 
-## When to Use
+## Start By Clarifying
+- Who participates in the process and where responsibilities change hands.
+- What the entry criteria, checkpoints, and exit criteria should be.
+- Which decisions require sign-off, escalation, or documented rationale.
+- What artifacts, links, or evidence should exist at each stage.
+- How the process should stay lightweight enough to be followed in practice.
 
-- You need help with architecture decision records.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the objective of the process and the scenarios it is meant to cover.
+2. Map the stages, decision points, owners, and required artifacts.
+3. Make review gates, success criteria, and escalation rules explicit.
+4. Add examples, templates, or checklists where teams commonly drift.
+5. Document how the process is maintained when the system or team changes.
 
-## Output
+## Good Output
+- Process outline with roles, sequence, and decision gates.
+- Required artifacts, examples, or checklists.
+- Open questions or edge cases that need policy rather than improvisation.
+- Maintenance notes so the process stays current.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Describing the ideal path but omitting ownership and exception handling.
+- Adding heavy ceremony without clear value or decision support.
+- Failing to show what done looks like at each stage.
+- Letting the process drift from how teams actually work.
+
+## Boundaries
+- Do not confuse process guidance with proof that the process is already being followed.
+- Prefer concrete responsibilities and exit criteria over vague workflow prose.

skills/documentation/backend-to-frontend-handoff-docs/SKILL.md

@@ -1,20 +1,44 @@
 ---
 id: backend-to-frontend-handoff-docs
 name: Backend-to-Frontend Handoff Docs
-description: Step-by-step guidance for backend-to-frontend handoff docs.
+description: Document backend-to-frontend handoff docs with clear responsibilities, decision points, sequencing, and follow-through expectations.
 category: Documentation
+requires: []
+examples:
+  - "Document backend-to-frontend handoff docs so contributors know the flow, roles, and exit criteria."
+  - "Turn this loose workflow into backend-to-frontend handoff docs with checkpoints, ownership, and review gates."
 ---
 
-# Backend To Frontend Handoff Docs
+# Backend-to-Frontend Handoff Docs
 
-Support backend to frontend handoff docs workflows with clear steps and best practices.
+Use this skill when the user needs backend-to-frontend handoff docs that turn an informal workflow into something reviewable, teachable, and easier to execute consistently.
 
-## When to Use
+## Start By Clarifying
+- Who participates in the process and where responsibilities change hands.
+- What the entry criteria, checkpoints, and exit criteria should be.
+- Which decisions require sign-off, escalation, or documented rationale.
+- What artifacts, links, or evidence should exist at each stage.
+- How the process should stay lightweight enough to be followed in practice.
 
-- You need help with backend to frontend handoff docs.
-- You want a clear, actionable next step.
+## Workflow
+1. Define the objective of the process and the scenarios it is meant to cover.
+2. Map the stages, decision points, owners, and required artifacts.
+3. Make review gates, success criteria, and escalation rules explicit.
+4. Add examples, templates, or checklists where teams commonly drift.
+5. Document how the process is maintained when the system or team changes.
 
-## Output
+## Good Output
+- Process outline with roles, sequence, and decision gates.
+- Required artifacts, examples, or checklists.
+- Open questions or edge cases that need policy rather than improvisation.
+- Maintenance notes so the process stays current.
 
-- Summary of goals and plan
-- Key tips and precautions
+## Common Pitfalls
+- Describing the ideal path but omitting ownership and exception handling.
+- Adding heavy ceremony without clear value or decision support.
+- Failing to show what done looks like at each stage.
+- Letting the process drift from how teams actually work.
+
+## Boundaries
+- Do not confuse process guidance with proof that the process is already being followed.
+- Prefer concrete responsibilities and exit criteria over vague workflow prose.