chore(skills): add Prowler Changelog skill (#9806)

2026-01-25 02:08:11 +00:00 · 2026-01-16 13:31:34 +01:00
parent aa24034ca7
commit d7af97b30a
10 changed files with 338 additions and 8 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,6 +38,7 @@ Use these skills for detailed patterns on-demand:
 | `prowler-compliance` | Compliance framework structure | [SKILL.md](skills/prowler-compliance/SKILL.md) |
 | `prowler-compliance-review` | Review compliance framework PRs | [SKILL.md](skills/prowler-compliance-review/SKILL.md) |
 | `prowler-provider` | Add new cloud providers | [SKILL.md](skills/prowler-provider/SKILL.md) |
+| `prowler-changelog` | Changelog entries (keepachangelog.com) | [SKILL.md](skills/prowler-changelog/SKILL.md) |
 | `prowler-ci` | CI checks and PR gates (GitHub Actions) | [SKILL.md](skills/prowler-ci/SKILL.md) |
 | `prowler-pr` | Pull request conventions | [SKILL.md](skills/prowler-pr/SKILL.md) |
 | `prowler-docs` | Documentation style guide | [SKILL.md](skills/prowler-docs/SKILL.md) |
@@ -49,11 +50,13 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:

 | Action | Skill |
 |--------|-------|
+| Add changelog entry for a PR or feature | `prowler-changelog` |
 | Adding new providers | `prowler-provider` |
 | Adding services to existing providers | `prowler-provider` |
 | After creating/modifying a skill | `skill-sync` |
 | App Router / Server Actions | `nextjs-15` |
 | Building AI chat features | `ai-sdk-5` |
+| Create PR that requires changelog entry | `prowler-changelog` |
 | Create a PR with gh pr create | `prowler-pr` |
 | Creating Zod schemas | `zod-4` |
 | Creating new checks | `prowler-sdk-check` |
@@ -71,6 +74,7 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 | Mocking AWS with moto in tests | `prowler-test-sdk` |
 | Regenerate AGENTS.md Auto-invoke tables (sync.sh) | `skill-sync` |
 | Review PR requirements: template, title conventions, changelog gate | `prowler-pr` |
+| Review changelog format and conventions | `prowler-changelog` |
 | Reviewing compliance framework PRs | `prowler-compliance-review` |
 | Testing RLS tenant isolation | `prowler-test-api` |
 | Troubleshoot why a skill is missing from AGENTS.md auto-invoke | `skill-sync` |
@@ -78,6 +82,7 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 | Understand PR title conventional-commit validation | `prowler-ci` |
 | Understand changelog gate and no-changelog label behavior | `prowler-ci` |
 | Understand review ownership with CODEOWNERS | `prowler-pr` |
+| Update CHANGELOG.md in any component | `prowler-changelog` |
 | Updating existing checks and metadata | `prowler-sdk-check` |
 | Using Zustand stores | `zustand-5` |
 | Working on MCP server tools | `prowler-mcp` |
--- a/api/AGENTS.md
+++ b/api/AGENTS.md
@@ -12,9 +12,13 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:

 | Action | Skill |
 |--------|-------|
+| Add changelog entry for a PR or feature | `prowler-changelog` |
+| Create PR that requires changelog entry | `prowler-changelog` |
 | Creating/modifying models, views, serializers | `prowler-api` |
 | Generic DRF patterns | `django-drf` |
+| Review changelog format and conventions | `prowler-changelog` |
 | Testing RLS tenant isolation | `prowler-test-api` |
+| Update CHANGELOG.md in any component | `prowler-changelog` |
 | Writing Prowler API tests | `prowler-test-api` |
 | Writing Python tests with pytest | `pytest` |

--- a/mcp_server/AGENTS.md
+++ b/mcp_server/AGENTS.md
@@ -1,6 +1,18 @@
 # Prowler MCP Server - AI Agent Ruleset

-> **Skills Reference**: For detailed patterns, use the [`prowler-mcp`](../skills/prowler-mcp/SKILL.md) skill.
+> **Skills Reference**: See [`prowler-mcp`](../skills/prowler-mcp/SKILL.md)
+
+### Auto-invoke Skills
+
+When performing these actions, ALWAYS invoke the corresponding skill FIRST:
+
+| Action | Skill |
+|--------|-------|
+| Add changelog entry for a PR or feature | `prowler-changelog` |
+| Create PR that requires changelog entry | `prowler-changelog` |
+| Review changelog format and conventions | `prowler-changelog` |
+| Update CHANGELOG.md in any component | `prowler-changelog` |
+| Working on MCP server tools | `prowler-mcp` |

 ## Project Overview

--- a/prowler/AGENTS.md
+++ b/prowler/AGENTS.md
@@ -13,13 +13,17 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:

 | Action | Skill |
 |--------|-------|
+| Add changelog entry for a PR or feature | `prowler-changelog` |
 | Adding new providers | `prowler-provider` |
 | Adding services to existing providers | `prowler-provider` |
+| Create PR that requires changelog entry | `prowler-changelog` |
 | Creating new checks | `prowler-sdk-check` |
 | Creating/updating compliance frameworks | `prowler-compliance` |
 | Mapping checks to compliance controls | `prowler-compliance` |
 | Mocking AWS with moto in tests | `prowler-test-sdk` |
+| Review changelog format and conventions | `prowler-changelog` |
 | Reviewing compliance framework PRs | `prowler-compliance-review` |
+| Update CHANGELOG.md in any component | `prowler-changelog` |
 | Updating existing checks and metadata | `prowler-sdk-check` |
 | Writing Prowler SDK tests | `prowler-test-sdk` |
 | Writing Python tests with pytest | `pytest` |
--- a/skills/prowler-changelog/SKILL.md
+++ b/skills/prowler-changelog/SKILL.md
@@ -0,0 +1,214 @@
+---
+name: prowler-changelog
+description: >
+  Manages changelog entries for Prowler components following keepachangelog.com format.
+  Trigger: When creating PRs, adding changelog entries, or working with any CHANGELOG.md file in ui/, api/, mcp_server/, or prowler/.
+license: Apache-2.0
+metadata:
+  author: prowler-cloud
+  version: "1.0"
+  scope: [root, ui, api, sdk, mcp_server]
+  auto_invoke:
+    - "Add changelog entry for a PR or feature"
+    - "Update CHANGELOG.md in any component"
+    - "Create PR that requires changelog entry"
+    - "Review changelog format and conventions"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+## Changelog Locations
+
+| Component | File | Version Prefix | Current Version |
+|-----------|------|----------------|-----------------|
+| UI | `ui/CHANGELOG.md` | None | 1.x.x |
+| API | `api/CHANGELOG.md` | None | 1.x.x |
+| MCP Server | `mcp_server/CHANGELOG.md` | None | 0.x.x |
+| SDK | `prowler/CHANGELOG.md` | None | 5.x.x |
+
+## Format Rules (keepachangelog.com)
+
+### Section Order (ALWAYS this order)
+
+```markdown
+## [X.Y.Z] (Prowler vA.B.C) OR (Prowler UNRELEASED)
+
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+```
+
+### Emoji Prefixes (REQUIRED for ALL components)
+
+| Section | Emoji | Usage |
+|---------|-------|-------|
+| Added | `### 🚀 Added` | New features, checks, endpoints |
+| Changed | `### 🔄 Changed` | Modifications to existing functionality |
+| Deprecated | `### ⚠️ Deprecated` | Features marked for removal |
+| Removed | `### ❌ Removed` | Deleted features |
+| Fixed | `### 🐞 Fixed` | Bug fixes |
+| Security | `### 🔐 Security` | Security patches, CVE fixes |
+
+### Entry Format
+
+```markdown
+### Added
+
+- First entry [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- Second entry [(#YYYY)](https://github.com/prowler-cloud/prowler/pull/YYYY)
+
+### Changed
+
+- Another entry [(#ZZZZ)](https://github.com/prowler-cloud/prowler/pull/ZZZZ)
+```
+
+**Rules:**
+- **Blank line after section header** before first entry
+- **Blank line between sections**
+- Be specific: what changed, not why (that's in the PR)
+- One entry per PR (can link multiple PRs for related changes)
+- No period at the end
+- Do NOT start with redundant verbs (section header already provides the action)
+
+### Semantic Versioning Rules
+
+Prowler follows [semver.org](https://semver.org/):
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fixes, patches | PATCH (x.y.**Z**) | 1.16.1 → 1.16.2 |
+| New features (backwards compatible) | MINOR (x.**Y**.0) | 1.16.2 → 1.17.0 |
+| Breaking changes, removals | MAJOR (**X**.0.0) | 1.17.0 → 2.0.0 |
+
+**CRITICAL:** `### ❌ Removed` entries MUST only appear in MAJOR version releases. Removing features is a breaking change.
+
+### Released Versions Are Immutable
+
+**NEVER modify already released versions.** Once a version is released (has a Prowler version tag like `v5.16.0`), its changelog section is frozen.
+
+**Common issue:** A PR is created during release cycle X, includes a changelog entry, but merges after release. The entry is now in the wrong section.
+
+```markdown
+## [1.16.0] (Prowler v5.16.0)    ← RELEASED, DO NOT MODIFY
+
+### Added
+- Feature from merged PR [(#9999)]   ← WRONG! PR merged after release
+
+## [1.17.0] (Prowler UNRELEASED)  ← Move entry HERE
+```
+
+**Fix:** Move the entry from the released version to the UNRELEASED section.
+
+### Version Header Format
+
+```markdown
+## [1.17.0] (Prowler UNRELEASED)    # For unreleased changes
+## [1.16.0] (Prowler v5.16.0)       # For released versions
+
+---                                  # Horizontal rule between versions
+```
+
+## Adding a Changelog Entry
+
+### Step 1: Determine Affected Component(s)
+
+```bash
+# Check which files changed
+git diff main...HEAD --name-only
+```
+
+| Path Pattern | Component |
+|--------------|-----------|
+| `ui/**` | UI |
+| `api/**` | API |
+| `mcp_server/**` | MCP Server |
+| `prowler/**` | SDK |
+| Multiple | Update ALL affected changelogs |
+
+### Step 2: Determine Change Type
+
+| Change | Section |
+|--------|---------|
+| New feature, check, endpoint | 🚀 Added |
+| Behavior change, refactor | 🔄 Changed |
+| Bug fix | 🐞 Fixed |
+| CVE patch, security improvement | 🔐 Security |
+| Feature removal | ❌ Removed |
+| Deprecation notice | ⚠️ Deprecated |
+
+### Step 3: Add Entry to UNRELEASED Section
+
+```bash
+# Example: Adding a fix to UI changelog
+```
+
+```markdown
+## [1.17.0] (Prowler UNRELEASED)
+
+### 🐞 Fixed
+
+- Button alignment in dashboard header [(#9999)](https://github.com/prowler-cloud/prowler/pull/9999)
+```
+
+## Examples
+
+### Good Entries
+
+```markdown
+### 🚀 Added
+- Search bar when adding a provider [(#9634)](https://github.com/prowler-cloud/prowler/pull/9634)
+
+### 🐞 Fixed
+- OCI update credentials form failing silently due to missing provider UID [(#9746)](https://github.com/prowler-cloud/prowler/pull/9746)
+
+### 🔐 Security
+- Node.js from 20.x to 24.13.0 LTS, patching 8 CVEs [(#9797)](https://github.com/prowler-cloud/prowler/pull/9797)
+```
+
+### Bad Entries
+
+```markdown
+- Fixed bug.                              # Too vague, has period
+- Added new feature for users             # Missing PR link, redundant verb
+- Add search bar [(#123)]                 # Redundant verb (section already says "Added")
+- This PR adds a cool new thing (#123)    # Wrong link format, conversational
+```
+
+## PR Changelog Gate
+
+The `pr-check-changelog.yml` workflow enforces changelog entries:
+
+1. **REQUIRED**: PRs touching `ui/`, `api/`, `mcp_server/`, or `prowler/` MUST update the corresponding changelog
+2. **SKIP**: Add `no-changelog` label to bypass (use sparingly for docs-only, CI-only changes)
+
+## Commands
+
+```bash
+# Check which changelogs need updates based on changed files
+git diff main...HEAD --name-only | grep -E '^(ui|api|mcp_server|prowler)/' | cut -d/ -f1 | sort -u
+
+# View current UNRELEASED section
+head -50 ui/CHANGELOG.md
+head -50 api/CHANGELOG.md
+head -50 mcp_server/CHANGELOG.md
+head -50 prowler/CHANGELOG.md
+```
+
+## Migration Note
+
+**API, MCP Server, and SDK changelogs currently lack emojis.** When editing these files, add emoji prefixes to section headers as you update them:
+
+```markdown
+# Before (legacy)
+### Added
+
+# After (standardized)
+### 🚀 Added
+```
+
+## Resources
+
+- **Templates**: See [assets/](assets/) for entry templates
+- **keepachangelog.com**: https://keepachangelog.com/en/1.1.0/
--- a/skills/prowler-changelog/assets/entry-templates.md
+++ b/skills/prowler-changelog/assets/entry-templates.md
@@ -0,0 +1,85 @@
+# Changelog Entry Templates
+
+## Section Headers
+
+```markdown
+### 🚀 Added
+### 🔄 Changed
+### ⚠️ Deprecated
+### ❌ Removed
+### 🐞 Fixed
+### 🔐 Security
+```
+
+## Entry Patterns
+
+> **Note:** Section headers already provide the verb. Entries describe WHAT, not the action.
+
+### Feature Addition (🚀 Added)
+```markdown
+- Search bar when adding a provider [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- `{check_id}` check for {provider} provider [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- `/api/v1/{endpoint}` endpoint to {description} [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+```
+
+### Behavior Change (🔄 Changed)
+```markdown
+- Lighthouse AI MCP tool filtering from blacklist to whitelist approach [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- {package} from {old} to {new} [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+```
+
+### Bug Fix (🐞 Fixed)
+```markdown
+- OCI update credentials form failing silently due to missing provider UID [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- {What was broken} in {component} [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+```
+
+### Security Patch (🔐 Security)
+```markdown
+- Node.js from 20.x to 24.13.0 LTS, patching 8 CVEs [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+- {package} to version {version} (CVE-XXXX-XXXXX) [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+```
+
+### Removal (❌ Removed)
+```markdown
+- Deprecated {feature} from {location} [(#XXXX)](https://github.com/prowler-cloud/prowler/pull/XXXX)
+```
+
+## Version Header Templates
+
+### Unreleased
+```markdown
+## [X.Y.Z] (Prowler UNRELEASED)
+```
+
+### Released
+```markdown
+## [X.Y.Z] (Prowler vA.B.C)
+
+---
+```
+
+## Full Entry Example
+
+```markdown
+## [1.17.0] (Prowler UNRELEASED)
+
+### 🚀 Added
+
+- Search bar when adding a provider [(#9634)](https://github.com/prowler-cloud/prowler/pull/9634)
+- New findings table UI with new design system components [(#9699)](https://github.com/prowler-cloud/prowler/pull/9699)
+
+### 🔄 Changed
+
+- Lighthouse AI MCP tool filtering from blacklist to whitelist approach [(#9802)](https://github.com/prowler-cloud/prowler/pull/9802)
+
+### 🐞 Fixed
+
+- OCI update credentials form failing silently due to missing provider UID [(#9746)](https://github.com/prowler-cloud/prowler/pull/9746)
+
+### 🔐 Security
+
+- Node.js from 20.x to 24.13.0 LTS, patching 8 CVEs [(#9797)](https://github.com/prowler-cloud/prowler/pull/9797)
+
+---
+```
--- a/skills/prowler-mcp/SKILL.md
+++ b/skills/prowler-mcp/SKILL.md
@@ -8,7 +8,7 @@ license: Apache-2.0
 metadata:
  author: prowler-cloud
  version: "1.0"
-  scope: [root]
+  scope: [root, mcp_server]
  auto_invoke: "Working on MCP server tools"
 allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
 ---
--- a/skills/skill-sync/SKILL.md
+++ b/skills/skill-sync/SKILL.md
@@ -48,6 +48,7 @@ metadata:
 | `ui` | `ui/AGENTS.md` |
 | `api` | `api/AGENTS.md` |
 | `sdk` | `prowler/AGENTS.md` |
+| `mcp_server` | `mcp_server/AGENTS.md` |

 Skills can have multiple scopes: `scope: [ui, api]`

--- a/skills/skill-sync/assets/sync.sh
+++ b/skills/skill-sync/assets/sync.sh
@@ -35,7 +35,7 @@ while [[ $# -gt 0 ]]; do
            echo ""
            echo "Options:"
            echo "  --dry-run    Show what would change without modifying files"
-            echo "  --scope      Only sync specific scope (root, ui, api, sdk)"
+            echo "  --scope      Only sync specific scope (root, ui, api, sdk, mcp_server)"
            exit 0
            ;;
        *)
@@ -53,6 +53,7 @@ get_agents_path() {
        ui)         echo "$REPO_ROOT/ui/AGENTS.md" ;;
        api)        echo "$REPO_ROOT/api/AGENTS.md" ;;
        sdk)        echo "$REPO_ROOT/prowler/AGENTS.md" ;;
+        mcp_server) echo "$REPO_ROOT/mcp_server/AGENTS.md" ;;
        *)          echo "" ;;
    esac
 }
--- a/ui/AGENTS.md
+++ b/ui/AGENTS.md
@@ -18,10 +18,14 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:

 | Action | Skill |
 |--------|-------|
+| Add changelog entry for a PR or feature | `prowler-changelog` |
 | App Router / Server Actions | `nextjs-15` |
 | Building AI chat features | `ai-sdk-5` |
+| Create PR that requires changelog entry | `prowler-changelog` |
 | Creating Zod schemas | `zod-4` |
 | Creating/modifying Prowler UI components | `prowler-ui` |
+| Review changelog format and conventions | `prowler-changelog` |
+| Update CHANGELOG.md in any component | `prowler-changelog` |
 | Using Zustand stores | `zustand-5` |
 | Working on Prowler UI structure (actions/adapters/types/hooks) | `prowler-ui` |
 | Working with Prowler UI test helpers/pages | `prowler-test-ui` |