diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md index 11787abe2b..5fa0480e42 100644 --- a/skills/skill-creator/SKILL.md +++ b/skills/skill-creator/SKILL.md @@ -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) diff --git a/skills/skill-sync/SKILL.md b/skills/skill-sync/SKILL.md index 9da79ccba6..2912b46dd8 100644 --- a/skills/skill-sync/SKILL.md +++ b/skills/skill-sync/SKILL.md @@ -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 `. | +| 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 `. +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)