mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-05-15 08:42:22 +00:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Alan Buscaglia
|
7c71038e1f |
+36
-149
@@ -1,8 +1,6 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: >
|
||||
Creates new AI agent skills following the Agent Skills spec.
|
||||
Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI.
|
||||
description: "Trigger: When user asks to create a new skill, add agent instructions, or document patterns for AI. Creates new AI agent skills following the Agent Skills spec."
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: prowler-cloud
|
||||
@@ -12,160 +10,49 @@ metadata:
|
||||
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
|
||||
---
|
||||
|
||||
## When to Create a Skill
|
||||
## Activation Contract
|
||||
|
||||
Create a skill when:
|
||||
- A pattern is used repeatedly and AI needs guidance
|
||||
- Project-specific conventions differ from generic best practices
|
||||
- Complex workflows need step-by-step instructions
|
||||
- Decision trees help AI choose the right approach
|
||||
Use this skill when the task is to create a new skill or reshape rough agent guidance into a reusable skill package.
|
||||
|
||||
**Don't create a skill when:**
|
||||
- Documentation already exists (create a reference instead)
|
||||
- Pattern is trivial or self-explanatory
|
||||
- It's a one-off task
|
||||
## Hard Rules
|
||||
|
||||
---
|
||||
- Create a skill only for reusable, non-trivial patterns.
|
||||
- Keep `description` on one quoted physical line with `Trigger:` first.
|
||||
- Use local references only; never point `references/` at web URLs.
|
||||
- Prefer short rules, decision tables, and minimal examples over tutorials.
|
||||
- Add `metadata.scope` and `metadata.auto_invoke` when the skill should surface in `AGENTS.md` auto-invoke tables.
|
||||
- Do not duplicate long docs inside the skill; point to local references instead.
|
||||
|
||||
## Skill Structure
|
||||
## Decision Gates
|
||||
|
||||
```
|
||||
skills/{skill-name}/
|
||||
├── SKILL.md # Required - main skill file
|
||||
├── assets/ # Optional - templates, schemas, examples
|
||||
│ ├── template.py
|
||||
│ └── schema.json
|
||||
└── references/ # Optional - links to local docs
|
||||
└── docs.md # Points to docs/developer-guide/*.mdx
|
||||
```
|
||||
| Question | Action |
|
||||
|---|---|
|
||||
| Is the pattern already documented well enough? | Reuse or reference the existing doc instead of creating a new skill. |
|
||||
| Is the guidance specific to this repo or workflow? | Create a project-specific skill name such as `prowler-{component}` or `{action}-{target}`. |
|
||||
| Do you need templates, schemas, or example configs? | Put them in `assets/`. |
|
||||
| Do you need supporting documentation? | Link only local files from `references/`. |
|
||||
| Will the skill be auto-invoked from `AGENTS.md`? | Add or update `metadata.scope` and `metadata.auto_invoke`, then decide whether `skill-sync` must run. |
|
||||
|
||||
---
|
||||
## Execution Steps
|
||||
|
||||
## SKILL.md Template
|
||||
1. Confirm the skill does not already exist under `skills/`.
|
||||
2. Choose a reusable name that matches the repo naming conventions.
|
||||
3. Create `skills/{skill-name}/SKILL.md` and required support folders only if needed (`assets/`, `references/`).
|
||||
4. Write frontmatter with `name`, one-line quoted `description`, `license`, and metadata.
|
||||
5. Write the body in this order: Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
|
||||
6. Keep the body compact: operational instructions first, examples only when they unblock execution.
|
||||
7. If auto-invoke metadata changed, run the `skill-sync` workflow appropriate to the scope.
|
||||
8. Update any non-generated skill index entries the repository expects.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {skill-name}
|
||||
description: >
|
||||
{One-line description of what this skill does}.
|
||||
Trigger: {When the AI should load this skill}.
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: prowler-cloud
|
||||
version: "1.0"
|
||||
---
|
||||
## Output Contract
|
||||
|
||||
## When to Use
|
||||
- Return the created or updated skill path(s).
|
||||
- State whether auto-invoke metadata changed and whether `skill-sync` was run, dry-run, or intentionally skipped.
|
||||
- Summarize the reusable pattern the skill captures in 1-3 bullets.
|
||||
- Call out any follow-up files the human should review, such as `AGENTS.md` or assets/templates.
|
||||
|
||||
{Bullet points of when to use this skill}
|
||||
## References
|
||||
|
||||
## Critical Patterns
|
||||
|
||||
{The most important rules - what AI MUST know}
|
||||
|
||||
## Code Examples
|
||||
|
||||
{Minimal, focused examples}
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
{Common commands}
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **Templates**: See [assets/](assets/) for {description}
|
||||
- **Documentation**: See [references/](references/) for local docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Type | Pattern | Examples |
|
||||
|------|---------|----------|
|
||||
| Generic skill | `{technology}` | `pytest`, `playwright`, `typescript` |
|
||||
| Prowler-specific | `prowler-{component}` | `prowler-api`, `prowler-ui`, `prowler-sdk-check` |
|
||||
| Testing skill | `prowler-test-{component}` | `prowler-test-sdk`, `prowler-test-api` |
|
||||
| Workflow skill | `{action}-{target}` | `skill-creator`, `jira-task` |
|
||||
|
||||
---
|
||||
|
||||
## Decision: assets/ vs references/
|
||||
|
||||
```
|
||||
Need code templates? → assets/
|
||||
Need JSON schemas? → assets/
|
||||
Need example configs? → assets/
|
||||
Link to existing docs? → references/
|
||||
Link to external guides? → references/ (with local path)
|
||||
```
|
||||
|
||||
**Key Rule**: `references/` should point to LOCAL files (`docs/developer-guide/*.mdx`), not web URLs.
|
||||
|
||||
---
|
||||
|
||||
## Decision: Prowler-Specific vs Generic
|
||||
|
||||
```
|
||||
Patterns apply to ANY project? → Generic skill (e.g., pytest, typescript)
|
||||
Patterns are Prowler-specific? → prowler-{name} skill
|
||||
Generic skill needs Prowler info? → Add references/ pointing to Prowler docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Skill identifier (lowercase, hyphens) |
|
||||
| `description` | Yes | What + Trigger in one block |
|
||||
| `license` | Yes | Always `Apache-2.0` for Prowler |
|
||||
| `metadata.author` | Yes | `prowler-cloud` |
|
||||
| `metadata.version` | Yes | Semantic version as string |
|
||||
|
||||
---
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### DO
|
||||
- Start with the most critical patterns
|
||||
- Use tables for decision trees
|
||||
- Keep code examples minimal and focused
|
||||
- Include Commands section with copy-paste commands
|
||||
|
||||
### DON'T
|
||||
- Add Keywords section (agent searches frontmatter, not body)
|
||||
- Duplicate content from existing docs (reference instead)
|
||||
- Include lengthy explanations (link to docs)
|
||||
- Add troubleshooting sections (keep focused)
|
||||
- Use web URLs in references (use local paths)
|
||||
|
||||
---
|
||||
|
||||
## Registering the Skill
|
||||
|
||||
After creating the skill, add it to `AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
| `{skill-name}` | {Description} | [SKILL.md](skills/{skill-name}/SKILL.md) |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Creating
|
||||
|
||||
- [ ] Skill doesn't already exist (check `skills/`)
|
||||
- [ ] Pattern is reusable (not one-off)
|
||||
- [ ] Name follows conventions
|
||||
- [ ] Frontmatter is complete (description includes trigger keywords)
|
||||
- [ ] Critical patterns are clear
|
||||
- [ ] Code examples are minimal
|
||||
- [ ] Commands section exists
|
||||
- [ ] Added to AGENTS.md
|
||||
|
||||
## Resources
|
||||
|
||||
- **Templates**: See [assets/](assets/) for SKILL.md template
|
||||
- [Template](assets/SKILL-TEMPLATE.md)
|
||||
- [Skills overview](../README.md)
|
||||
- [Repository agent rules](../../AGENTS.md)
|
||||
|
||||
+33
-96
@@ -1,8 +1,6 @@
|
||||
---
|
||||
name: skill-sync
|
||||
description: >
|
||||
Syncs skill metadata to AGENTS.md Auto-invoke sections.
|
||||
Trigger: When updating skill metadata (metadata.scope/metadata.auto_invoke), regenerating Auto-invoke tables, or running ./skills/skill-sync/assets/sync.sh (including --dry-run/--scope).
|
||||
description: "Trigger: When updating skill metadata (metadata.scope/metadata.auto_invoke), regenerating Auto-invoke tables, or running ./skills/skill-sync/assets/sync.sh. Syncs skill metadata to AGENTS.md Auto-invoke sections."
|
||||
license: Apache-2.0
|
||||
metadata:
|
||||
author: prowler-cloud
|
||||
@@ -15,107 +13,46 @@ metadata:
|
||||
allowed-tools: Read, Edit, Write, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
## Purpose
|
||||
## Activation Contract
|
||||
|
||||
Keeps AGENTS.md Auto-invoke sections in sync with skill metadata. When you create or modify a skill, run the sync script to automatically update all affected AGENTS.md files.
|
||||
Use this skill when a skill's `metadata.scope` or `metadata.auto_invoke` changes, when auto-invoke tables need regeneration, or when a skill is missing from `AGENTS.md` auto-invoke output.
|
||||
|
||||
## Required Skill Metadata
|
||||
## Hard Rules
|
||||
|
||||
Each skill that should appear in Auto-invoke sections needs these fields in `metadata`.
|
||||
- Treat `./skills/skill-sync/assets/sync.sh` as the source of truth for generated auto-invoke tables.
|
||||
- Do not hand-edit generated auto-invoke sections unless the workflow itself is being fixed.
|
||||
- Run `--dry-run` first when you only need verification or when metadata impact is uncertain.
|
||||
- Only `metadata.scope` and `metadata.auto_invoke` should drive sync decisions.
|
||||
- Keep scope values aligned to real targets: `root`, `ui`, `api`, `sdk`, `mcp_server`.
|
||||
|
||||
`auto_invoke` can be either a single string **or** a list of actions:
|
||||
## Decision Gates
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
author: prowler-cloud
|
||||
version: "1.0"
|
||||
scope: [ui] # Which AGENTS.md: ui, api, sdk, root
|
||||
| Question | Action |
|
||||
|---|---|
|
||||
| Did `metadata.scope` or `metadata.auto_invoke` change? | Run `sync.sh` for real, or `--scope` if the blast radius is intentionally narrow. |
|
||||
| Did only body text or examples change? | Skip sync and say why; generated tables are unaffected. |
|
||||
| Are you checking expected output without modifying files? | Run `sync.sh --dry-run`. |
|
||||
| Is one surface affected? | Use `sync.sh --scope <scope>`. |
|
||||
| Is a skill missing from auto-invoke output? | Inspect its frontmatter first, then run `--dry-run` to confirm what the script sees. |
|
||||
|
||||
# Option A: single action
|
||||
auto_invoke: "Creating/modifying components"
|
||||
## Execution Steps
|
||||
|
||||
# Option B: multiple actions
|
||||
# auto_invoke:
|
||||
# - "Creating/modifying components"
|
||||
# - "Refactoring component folder placement"
|
||||
```
|
||||
1. Read the changed skill frontmatter and confirm `metadata.scope` and `metadata.auto_invoke` are present and well-formed.
|
||||
2. Decide whether the task needs a real sync, a dry-run, or a documented no-op.
|
||||
3. If validating only, run `./skills/skill-sync/assets/sync.sh --dry-run`.
|
||||
4. If updating one target, run `./skills/skill-sync/assets/sync.sh --scope <scope>`.
|
||||
5. If updating all affected targets, run `./skills/skill-sync/assets/sync.sh`.
|
||||
6. Verify the expected `AGENTS.md` surfaces changed only where metadata demanded it.
|
||||
|
||||
### Scope Values
|
||||
## Output Contract
|
||||
|
||||
| Scope | Updates |
|
||||
|-------|---------|
|
||||
| `root` | `AGENTS.md` (repo root) |
|
||||
| `ui` | `ui/AGENTS.md` |
|
||||
| `api` | `api/AGENTS.md` |
|
||||
| `sdk` | `prowler/AGENTS.md` |
|
||||
| `mcp_server` | `mcp_server/AGENTS.md` |
|
||||
- State whether sync was executed, dry-run only, or skipped as a no-op.
|
||||
- List the scope(s) evaluated and the `AGENTS.md` file(s) affected or intentionally untouched.
|
||||
- If the issue was missing auto-invoke output, explain the root cause in the skill metadata or script behavior.
|
||||
- Return the exact command used for verification or update.
|
||||
|
||||
Skills can have multiple scopes: `scope: [ui, api]`
|
||||
## References
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### After Creating/Modifying a Skill
|
||||
|
||||
```bash
|
||||
./skills/skill-sync/assets/sync.sh
|
||||
```
|
||||
|
||||
### What It Does
|
||||
|
||||
1. Reads all `skills/*/SKILL.md` files
|
||||
2. Extracts `metadata.scope` and `metadata.auto_invoke`
|
||||
3. Generates Auto-invoke tables for each AGENTS.md
|
||||
4. Updates the `### Auto-invoke Skills` section in each file
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
Given this skill metadata:
|
||||
|
||||
```yaml
|
||||
# skills/prowler-ui/SKILL.md
|
||||
metadata:
|
||||
author: prowler-cloud
|
||||
version: "1.0"
|
||||
scope: [ui]
|
||||
auto_invoke: "Creating/modifying React components"
|
||||
```
|
||||
|
||||
The sync script generates in `ui/AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
### Auto-invoke Skills
|
||||
|
||||
When performing these actions, ALWAYS invoke the corresponding skill FIRST:
|
||||
|
||||
| Action | Skill |
|
||||
|--------|-------|
|
||||
| Creating/modifying React components | `prowler-ui` |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Sync all AGENTS.md files
|
||||
./skills/skill-sync/assets/sync.sh
|
||||
|
||||
# Dry run (show what would change)
|
||||
./skills/skill-sync/assets/sync.sh --dry-run
|
||||
|
||||
# Sync specific scope only
|
||||
./skills/skill-sync/assets/sync.sh --scope ui
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist After Modifying Skills
|
||||
|
||||
- [ ] Added `metadata.scope` to new/modified skill
|
||||
- [ ] Added `metadata.auto_invoke` with action description
|
||||
- [ ] Ran `./skills/skill-sync/assets/sync.sh`
|
||||
- [ ] Verified AGENTS.md files updated correctly
|
||||
- [Sync script](assets/sync.sh)
|
||||
- [Sync script test helper](assets/sync_test.sh)
|
||||
- [Repository agent rules](../../AGENTS.md)
|
||||
|
||||
Reference in New Issue
Block a user