gh-aw

Files (2)

• SKILL.md
• docs.md · references/

SKILL.md (first lines)

## 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

### AGENTS.md Is the Source of Truth

Agent personas MUST NOT hardcode codebase layout, file paths, skill names, tech stack versions, or project conventions. All of this lives in the repo's `AGENTS.md` files and WILL go stale if duplicated.

**Instead**: Instruct the agent to READ `AGENTS.md` at runtime:

```markdown
# In the agent persona:
Read `AGENTS.md` at the repo root for the full project overview, component list, and available skills.
```

For monorepos with component-specific `AGENTS.md` files, include a routing table that tells the agent WHICH file to read based on context — but never copy the contents of those files into the agent:

```markdown
| Component | AGENTS.md | When to read |
|-----------|-----------|-------------|
| Backend   | `api/AGENTS.md`    | API errors, endpoint bugs |
| Frontend  | `ui/AGENTS.md`     | UI crashes, rendering bugs |
| Root      | `AGENTS.md`        | Cross-component, CI/CD |
```

**Why this matters**: Agent personas are deployed as workflow files. When `AGENTS.md` updates (new skills, renamed paths, version bumps), agents that READ it at runtime get the update automatically. Agents that HARDCODE it require a separate PR to stay current — and they won't.

### 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. **IMPORTANT**: `strict: true` rejects custom domains in `network.allowed` — only ecosystem identifiers (`defaults`, `python`, `node`, etc.) are permitted. Workflows using custom MCP server domains (e.g., `mcp.prowler.com`) MUST use `strict: false`. This is an intentional tradeoff, not a development shortcut.

### 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"

From brivaro/brivaro-ai-wizard, Apache-2.0.

More from brivaro/brivaro-ai-wizard