diff --git a/AGENTS.md b/AGENTS.md index ad33f00dcf..657b8dc2d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ Use these skills for detailed patterns on-demand: | `prowler-pr` | Pull request conventions | [SKILL.md](skills/prowler-pr/SKILL.md) | | `prowler-docs` | Documentation style guide | [SKILL.md](skills/prowler-docs/SKILL.md) | | `prowler-attack-paths-query` | Create Attack Paths openCypher queries | [SKILL.md](skills/prowler-attack-paths-query/SKILL.md) | -| `prowler-gh-aw` | GitHub Agentic Workflows (gh-aw) | [SKILL.md](skills/prowler-gh-aw/SKILL.md) | +| `gh-aw` | GitHub Agentic Workflows (gh-aw) | [SKILL.md](skills/gh-aw/SKILL.md) | | `skill-creator` | Create new AI agent skills | [SKILL.md](skills/skill-creator/SKILL.md) | ### Auto-invoke Skills @@ -63,12 +63,12 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST: | App Router / Server Actions | `nextjs-15` | | Building AI chat features | `ai-sdk-5` | | Committing changes | `prowler-commit` | -| Configuring MCP servers in agentic workflows | `prowler-gh-aw` | +| Configuring MCP servers in agentic workflows | `gh-aw` | | Create PR that requires changelog entry | `prowler-changelog` | | Create a PR with gh pr create | `prowler-pr` | | Creating API endpoints | `jsonapi` | | Creating Attack Paths queries | `prowler-attack-paths-query` | -| Creating GitHub Agentic Workflows | `prowler-gh-aw` | +| Creating GitHub Agentic Workflows | `gh-aw` | | Creating ViewSets, serializers, or filters in api/ | `django-drf` | | Creating Zod schemas | `zod-4` | | Creating a git commit | `prowler-commit` | @@ -78,17 +78,17 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST: | Creating/modifying models, views, serializers | `prowler-api` | | Creating/updating compliance frameworks | `prowler-compliance` | | Debug why a GitHub Actions job is failing | `prowler-ci` | -| Debugging gh-aw compilation errors | `prowler-gh-aw` | +| Debugging gh-aw compilation errors | `gh-aw` | | Fill .github/pull_request_template.md (Context/Description/Steps to review/Checklist) | `prowler-pr` | | General Prowler development questions | `prowler` | | Implementing JSON:API endpoints | `django-drf` | -| Importing Copilot Custom Agents into workflows | `prowler-gh-aw` | +| Importing Copilot Custom Agents into workflows | `gh-aw` | | Inspect PR CI checks and gates (.github/workflows/*) | `prowler-ci` | | Inspect PR CI workflows (.github/workflows/*): conventional-commit, pr-check-changelog, pr-conflict-checker, labeler | `prowler-pr` | | Mapping checks to compliance controls | `prowler-compliance` | | Mocking AWS with moto in tests | `prowler-test-sdk` | | Modifying API responses | `jsonapi` | -| Modifying gh-aw workflow frontmatter or safe-outputs | `prowler-gh-aw` | +| Modifying gh-aw workflow frontmatter or safe-outputs | `gh-aw` | | 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` | diff --git a/skills/gh-aw/SKILL.md b/skills/gh-aw/SKILL.md new file mode 100644 index 0000000000..5d145adbe3 --- /dev/null +++ b/skills/gh-aw/SKILL.md @@ -0,0 +1,223 @@ +--- +name: gh-aw +description: > + Create and maintain GitHub Agentic Workflows (gh-aw) for Prowler. + Trigger: When creating agentic workflows, modifying gh-aw frontmatter, configuring safe-outputs, + setting up MCP servers in workflows, importing Copilot Custom Agents, or debugging gh-aw compilation. +license: Apache-2.0 +metadata: + author: prowler-cloud + version: "1.0" + scope: [root] + auto_invoke: + - "Creating GitHub Agentic Workflows" + - "Modifying gh-aw workflow frontmatter or safe-outputs" + - "Configuring MCP servers in agentic workflows" + - "Importing Copilot Custom Agents into workflows" + - "Debugging gh-aw compilation errors" +allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch +--- + +## When to Use + +- Creating new `.github/workflows/*.md` agentic workflows +- Modifying frontmatter (triggers, permissions, safe-outputs, tools, MCP servers) +- Creating or importing `.github/agents/*.md` Copilot Custom Agents +- Debugging `gh aw compile` errors or warnings +- Configuring network access, rate limits, or footer templates + +--- + +## File Layout + +``` +.github/ +├── workflows/ +│ ├── {name}.md # Frontmatter + thin context dispatcher +│ └── {name}.lock.yml # Auto-generated — NEVER edit manually +├── agents/ +│ └── {name}.md # Full agent persona (reusable) +└── aw/ + └── actions-lock.json # Action SHA pinning — commit this +``` + +See [references/](references/) for existing workflow and agent examples in this repo. + +--- + +## Critical Patterns + +### Two-File Architecture + +Workflow file = **config + context only**. Agent file = **all reasoning logic**. + +The workflow imports the agent via `imports:` and passes sanitized runtime context. The agent contains the persona, rules, steps, and output format. This separation makes agents reusable across workflows. + +### Import Path Resolution + +Paths resolve **relative to the importing file**, NOT from repo root: + +```yaml +# From .github/workflows/my-workflow.md: +imports: + - ../agents/my-agent.md # CORRECT + - .github/agents/my-agent.md # WRONG — resolves to .github/workflows/.github/agents/ +``` + +### Sanitized Context (Security) + +NEVER pass raw `github.event.issue.body` to the agent: + +```markdown +${{ needs.activation.outputs.text }} +``` + +### Read-Only Permissions + Safe Outputs + +Workflows run read-only. Writes go through `safe-outputs`: + +```yaml +# GOOD +permissions: + issues: read +safe-outputs: + add-comment: + hide-older-comments: true + +# BAD — never give the agent write access +permissions: + issues: write +``` + +### Strict Mode + +`strict: true` (default) enforces: no write permissions, explicit network config, no wildcard domains, ecosystem identifiers required. Set `strict: false` only during development. + +### Footer Control + +Prevent double footers with `messages.footer`: + +```yaml +safe-outputs: + messages: + footer: "> 🤖 Generated by [{workflow_name}]({run_url}) [Experimental]" +``` + +Variables: `{workflow_name}`, `{run_url}`, `{triggering_number}`, `{event_type}`, `{status}`. + +### MCP Servers + +Always use `allowed` to restrict tools. Add domains to `network.allowed`: + +```yaml +network: + allowed: + - "mcp.prowler.com" + +mcp-servers: + prowler: + url: "https://mcp.prowler.com/mcp" + allowed: + - prowler_hub_get_check_details + - prowler_hub_get_check_code + - prowler_docs_search +``` + +--- + +## Trigger Patterns + +| Pattern | Trigger | Use Case | +|---------|---------|----------| +| LabelOps | `issues.types: [labeled]` + `names: [label]` | Triage, review | +| ChatOps | `issue_comment` + command parsing | Bot commands | +| DailyOps | `schedule: daily` | Reports, maintenance | +| IssueOps | `issues.types: [opened]` | Auto-triage on creation | + +Dual-label gate (require trigger label + existing label): + +```yaml +on: + issues: + types: [labeled] + names: [ai-review] +if: contains(toJson(github.event.issue.labels), 'status/needs-triage') +``` + +--- + +## Safe Outputs Quick Reference + +| Type | What | Key options | +|------|------|-------------| +| `add-comment` | Post comment | `hide-older-comments`, `target` | +| `create-issue` | Create issue | `title-prefix`, `labels`, `close-older-issues`, `expires` | +| `add-labels` | Add labels | `allowed` (restrict to list) | +| `remove-labels` | Remove labels | `allowed` (restrict to list) | +| `create-pull-request` | Create PR | `max`, `target-repo` | +| `close-issue` | Close issue | `target`, `required-labels` | +| `update-issue` | Update fields | `status`, `title`, `body` | +| `dispatch-workflow` | Trigger workflow | `workflows` (list) | + +--- + +## AI Engines + +| Engine | Value | Notes | +|--------|-------|-------| +| GitHub Copilot | `copilot` | Default, supports Custom Agents | +| Claude | `claude` | Anthropic | +| OpenAI Codex | `codex` | OpenAI | + +--- + +## Commands + +```bash +# Compile workflows (regenerates lock files) +gh aw compile + +# Compile with strict validation +gh aw compile --strict + +# Check workflow status +gh aw status + +# Add a community workflow +gh aw add owner/repo/workflow.md + +# Trigger manually +gh aw run workflow-name + +# View logs +gh aw logs workflow-name +``` + +--- + +## Compilation Checklist + +After modifying any `.github/workflows/*.md`: + +- [ ] Run `gh aw compile` — check for errors +- [ ] Stage the `.lock.yml` alongside the `.md` +- [ ] Stage `.github/aw/actions-lock.json` if changed +- [ ] Verify `network.allowed` includes all MCP server domains +- [ ] Verify permissions are read-only (use safe-outputs for writes) + +--- + +## .gitattributes + +Add to repo root so lock files auto-resolve on merge: + +``` +.github/workflows/*.lock.yml linguist-generated=true merge=ours +``` + +--- + +## Resources + +- **Examples**: See [references/](references/) for existing workflow and agent files in this repo +- **Documentation**: See [references/](references/) for links to gh-aw official docs diff --git a/skills/gh-aw/references/docs.md b/skills/gh-aw/references/docs.md new file mode 100644 index 0000000000..8d840989a4 --- /dev/null +++ b/skills/gh-aw/references/docs.md @@ -0,0 +1,24 @@ +# GitHub Agentic Workflows Documentation + +## Local Examples + +Working workflow and agent files in this repo: + +- `.github/workflows/issue-triage.md` - Workflow frontmatter + context dispatcher (LabelOps pattern) +- `.github/agents/issue-triage.md` - Full triage agent persona with output format +- `.github/workflows/issue-triage.lock.yml` - Compiled lock file (auto-generated) +- `.github/aw/actions-lock.json` - Action SHA pinning +- `.gitattributes` - Lock file merge strategy + +## Official Documentation + +- gh-aw docs: https://github.github.com/gh-aw/ +- Frontmatter reference: https://github.github.com/gh-aw/reference/frontmatter/ +- Safe outputs: https://github.github.com/gh-aw/reference/safe-outputs/ +- Triggers: https://github.github.com/gh-aw/reference/triggers/ +- Tools: https://github.github.com/gh-aw/reference/tools/ +- MCP servers: https://github.github.com/gh-aw/guides/mcps/ +- Imports: https://github.github.com/gh-aw/reference/imports/ +- Network access: https://github.github.com/gh-aw/reference/network/ +- Design patterns: https://github.github.com/gh-aw/patterns/ +- Copilot Custom Agents: https://github.github.com/gh-aw/reference/copilot-custom-agents/