playbooks

home / skills / prowler-cloud / prowler / prowler-docs

prowler-docs skill

/skills/prowler-docs

This skill guides Prowler documentation writing with brand voice, structure, and SEO best practices for features, tutorials, and guides.

npx playbooks add skill prowler-cloud/prowler --skill prowler-docs

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.1 KB
---
name: prowler-docs
description: >
  Prowler documentation style guide and writing standards.
  Trigger: When writing documentation for Prowler features, tutorials, or guides.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.0"
  scope: [root]
  auto_invoke: "Writing documentation"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
---

## When to Use

Use this skill when writing Prowler documentation for:
- Feature documentation
- API/SDK references
- Tutorials and guides
- Release notes

## Brand Voice

### Unbiased Communication
- Avoid gendered pronouns (use "you/your" or "they/them")
- Use inclusive alternatives: businessman → businessperson, mankind → humanity
- No generalizations about gender, race, nationality, culture
- Avoid militaristic language: fight → address, kill chain → cyberattack chain

### Technical Terminology
- Define key terms and acronyms on first use: "Identity and Access Management (IAM)"
- Prefer verbal over nominal constructions: "The report was created" not "The creation of the report"
- Use clear, accessible language; minimize jargon

## Formatting Standards

### Title Case Capitalization
Use Title Case for all headers:
- Good: "How to Configure Security Scanning"
- Bad: "How to configure security scanning"

### Hyphenation
- Prenominal position: "world-leading company"
- Postnominal position: "features built in"

### Bullet Points
Use when information can be logically divided:
```markdown
Prowler CLI includes:
* **Industry standards:** CIS, NIST 800, NIST CSF
* **Regulatory compliance:** RBI, FedRAMP, PCI-DSS
* **Privacy frameworks:** GDPR, HIPAA, FFIEC
```

### Interaction Verbs
- Desktop: Click, Double-click, Right-click, Drag, Scroll
- Touch: Tap, Double-tap, Press and hold, Swipe, Pinch

## SEO Optimization

### Sentence Structure
Place keywords at the beginning:
- Good: "To create a custom role, open a terminal..."
- Bad: "Open a terminal to create a custom role..."

### Headers
- H1: Primary (unique, descriptive)
- H2-H6: Subheadings (logical hierarchy)
- Include keywords naturally

## MDX Components

### Version Badge
```mdx
import { VersionBadge } from "/snippets/version-badge.mdx"

## New Feature Name

<VersionBadge version="4.5.0" />

Description of the feature...
```

### Warnings and Danger Calls
```mdx
<Warning>
Disabling encryption may expose sensitive data to unauthorized access.
</Warning>

<Danger>
Running this command will **permanently delete all data**.
</Danger>
```

## Prowler Features (Proper Nouns)

Reference without articles:
- Prowler App, Prowler CLI, Prowler SDK
- Prowler Cloud, Prowler Studio, Prowler Registry
- Built-in Compliance Checks
- Multi-cloud Security Scanning
- Autonomous Cloud Security Analyst (AI)

## Documentation Structure

```
docs/
├── getting-started/
├── tutorials/
├── providers/
│   ├── aws/
│   ├── azure/
│   ├── gcp/
│   └── ...
├── api/
├── sdk/
├── compliance/
└── developer-guide/
```

## Resources

- **Documentation**: See [references/](references/) for links to local developer guide

Overview

This skill provides a concise style guide and writing standards for Prowler documentation. It ensures consistent voice, formatting, SEO, and MDX usage when authoring feature docs, tutorials, API references, and release notes. Use it to maintain clarity, inclusivity, and technical accuracy across all Prowler content.

How this skill works

The skill inspects documentation drafts for brand voice, terminology, header capitalization, hyphenation, and bullet structure. It validates MDX snippets such as VersionBadge and Warning/Danger components, checks SEO-friendly sentence placement, and enforces proper noun usage for Prowler features. It flags deviations and suggests edits to align content with the guide.

When to use it

  • Writing feature documentation for Prowler App, Prowler CLI, or Prowler Cloud
  • Creating API or SDK reference pages and examples
  • Authoring tutorials, how-tos, or step-by-step guides
  • Drafting release notes for new versions and features

Best practices

  • Use an unbiased, inclusive voice; avoid gendered pronouns and broad generalizations
  • Define key terms and acronyms on first use (e.g., Identity and Access Management (IAM))
  • Use Title Case for all headers and maintain logical H1–H6 hierarchy
  • Place keywords near the start of sentences and headers for better SEO
  • Follow hyphenation rules: use hyphen in prenominal position, none postnominal
  • Use MDX components for version badges and callouts; prefer clear, short code examples

Example use cases

  • Documenting a new compliance check added to Built-in Compliance Checks
  • Writing an SDK guide demonstrating Prowler SDK usage patterns
  • Creating a provider tutorial for AWS, Azure, or GCP under providers/
  • Preparing release notes with VersionBadge and feature summaries
  • Composing security-hardening how-to guides that include Warning and Danger callouts

FAQ

What voice should I use for Prowler docs?

Use an unbiased, inclusive, technical voice that avoids gendered language, militaristic metaphors, and unsupported generalizations.

How do I show a new feature version in MDX?

Import and use the VersionBadge component with the version prop, then add a brief feature description below it.