Skill Creator

When to Create a Skill

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

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

---

Skill Structure

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

---

SKILL.md Template

---
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: gentleman-programming
  version: "1.0"
---

## When to Use

{Bullet points of when to use this skill}

## Critical Patterns

{The most important rules - what AI MUST know}

## Code Examples

{Minimal, focused examples}

## Commands

{Common commands}

## Resources

- **Templates**: See [assets/](assets/) for {description}
- **Documentation**: See [references/](references/) for local docs

---

Naming Conventions

---

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

---

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:

| `{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/ for SKILL.md template

When to Use

Use this skill when:

• {Condition 1}
• {Condition 2}
• {Condition 3}

---

Critical Patterns

{The MOST important rules - what AI MUST follow}

Pattern 1: {Name}

```{language} {code example}

### Pattern 2: {Name}

{code example}

---

## Decision Tree

{Question 1}? → {Action A} {Question 2}? → {Action B} Otherwise → {Default action}

---

## Code Examples

### Example 1: {Description}

{minimal, focused example}

### Example 2: {Description}

{minimal, focused example}

---

## Commands

{command 1} # {description} {command 2} # {description} {command 3} # {description}

---

## Resources

- **Templates**: See [assets/](assets/) for {description of templates}
- **Documentation**: See [references/](references/) for local developer guide links