Documentation Skill

You are an expert at writing and maintaining documentation for Turbot Guardrails. This skill helps you create, update, and review documentation following the project's style guidelines and best practices.

Context Files

Before performing any documentation task, familiarize yourself with these guides:

• Style Guide - Complete formatting, structure, and style rules
• Prevention Guide - Prevention-specific concepts and guidance

When This Skill Applies

This skill activates when the user is:

• Writing or editing markdown documentation files
• Adding or updating screenshots
• Fixing formatting or link issues
• Reviewing documentation for compliance
• Asking about documentation standards or structure
• Working on files in the docs/ directory

Routing Logic

Based on the user's intent, route to the appropriate workflow:

Creating New Documentation

Trigger words: "write", "create", "add new page", "document" → Use workflows/new-page.md

Adding Screenshots

Trigger words: "screenshot", "add image", "take a picture", "capture" → Use workflows/add-screenshots.md

Fixing Links

Trigger words: "fix links", "update links", "broken links", "link format" → Use workflows/fix-links.md

Reviewing Documentation

Trigger words: "review", "check", "validate", "audit", "compliance check" → Use workflows/review.md

General Questions

If the user asks about style, structure, or best practices, answer directly using the context files.

Core Principles

When working on documentation:

1. Conversational Tone: Write naturally, explain WHY things matter, not just WHAT they are
2. Image Management:
   • Store in same directory as markdown
   • Use markdown syntax ![alt](./image.png)
   • Must resize browser to 1280px width before taking screenshots
3. Link Format:
   • Absolute paths starting with /guardrails
   • Omit .md extensions and index.md
4. Structure:
   • Each page in its own folder as index.md
   • All images for that page in the same folder
5. Headers:
   • One h1 matching frontmatter title
   • No ## Overview header
   • Start content immediately after h1

Working with Prevention Documentation

When documenting the Prevention section:

• Focus on explaining security concepts, not just UI elements
• Address common use cases (finding gaps, prioritizing work, testing controls)
• Explain the relationship between Objectives, Preventions, Layers, and Categories
• Use real examples (EBS encryption, S3 public access, etc.)
• Emphasize prevention-first security (stop issues before they reach production)

Quick Reference

DO:

• Write conversationally with purpose and context
• Explain capabilities and why they matter
• Include practical scenarios and use cases
• Use markdown image syntax and relative paths
• Use absolute link paths with /guardrails prefix

DON'T:

• Create exhaustive "Page Layout" bullet lists
• Just describe UI without explaining value
• Repeat the same link multiple times in a section
• Use HTML <img> tags (except when size specification needed)
• Use relative link paths or include .md extensions

Example Invocations

• "Write a new page documenting the prevention dashboard"
• "Add screenshots to the simulator documentation"
• "Fix all the links in the prevention section"
• "Review the objectives documentation for style compliance"
• "How should I format images in the docs?"
• "What's the correct link format for cross-references?"