Workflow Designer
Use this skill to run a structured interview with users who know their goal but not the workflow syntax yet, then generate one complete workflow .md file.
When to Use This Skill
Use this before .github/aw/create-agentic-workflow.md when requirements are unclear or incomplete.
- Use
skills/agentic-workflow-designer/SKILL.md to discover and confirm requirements.
- Use
.github/aw/create-agentic-workflow.md once requirements are clear and ready for implementation.
- Use
.github/aw/agentic-chat.md when the user wants a specification/pseudo-code instead of a runnable workflow file.
Interview Framework
Ask one question at a time. Move to the next phase only after the current phase is clear.
Phase 1: Goal
Ask: "What do you want to automate?"
Capture:
- Workflow name (kebab-case candidate)
- Brief description
- Optional emoji
Phase 2: Trigger
Ask: "When should this run?"
Follow up only if needed:
- Which event type(s)?
- Any filters (labels, branches, commands)?
- Scheduled cadence (daily/weekly/hourly)?
Map to the on: block.
Phase 3: Scope (Read/Write)
Ask:
- "What should it read?" (issues, PRs, code, discussions, CI data)
- "What should it create or update?" (comments, issues, PRs, labels)
Map to:
permissions: (keep read-only for agent job)
tools:
safe-outputs:
Phase 4: Data Strategy
Ask:
- "What data does the agent need to make decisions?"
- Follow up: "Can we pre-fetch and aggregate that data with shell commands so the agent only reads compact JSON?"
Capture:
- Whether
steps: should pre-fetch GitHub data with gh + jq
- Output paths under
/tmp/gh-aw/data/
- Whether batch work should use sub-agents
Map to:
steps:
- Prompt references to pre-computed file paths
Phase 5: Guardrails
Ask: "Should it block merging, just advise, or silently log?"
Capture:
- Visibility expectations (comment, issue, no visible output)
- No-op behavior expectation
Guide toward safe output behavior and explicit noop instructions.
Phase 6: Context & Network
Ask: "Does it need external APIs, web access, package installs, or MCP servers?"
Follow up:
- "Any third-party services or MCP servers to include (for example Slack, Jira, Datadog, custom internal MCP)?"
- "Are you deploying on GitHub.com, GHEC with custom endpoints, or GHES?"
- For each integration, identify required auth from source docs and map it to GitHub Actions secrets + workflow env variables.
- Ask for exact external domains (FQDN/wildcard).
Map to:
network.allowed
- Optional MCP/GitHub tool usage in
tools:
secrets: / env: wiring for integration tokens
- GHES/GHEC settings such as
engine.api-target and aw.json ghes: true (when applicable)
Phase 7: Engine (optional)
Ask only if ambiguous: "Any AI engine preference?"
If no preference, suggest default:
- "I'd suggest Copilot since you haven't mentioned a preference. Sound good?"
Map to engine: only when not default.
Phase 8: Confirmation
Present a structured summary and ask for approval before generation.
Decision Heuristics
Trigger Mapping
| User says... |
Maps to |
| "when someone opens a PR" |
on: pull_request: with types: [opened] |
| "when a PR is updated" |
on: pull_request: with types: [opened, synchronize] |
| "every morning", "daily" |
fuzzy schedule shorthand on: schedule: daily on weekdays (compiler expands to cron) |
| "every Monday", "weekly" |
fuzzy schedule shorthand on: schedule: weekly (compiler expands to cron) |
| "when I say /review" |
on: slash_command: with name: review (or requested command) |
| "when an issue is labeled bug" |
on: issues: with types: [labeled] and label filter guidance |
| "run when label ai-review is added" |
on: label_command: with name/names, optional event scoping, and label-as-command semantics |
| "run on PRs from forks" |
on: pull_request: plus explicit forks: allowlist and fork security guardrails |
| "sometimes automatic, sometimes manual" |
semi-active pattern: combine schedule/event triggers with workflow_dispatch |
| "manually", "on demand" |
on: workflow_dispatch: |
| "when a deployment fails" |
on: deployment_status: |
| "when another workflow finishes" |
on: workflow_run: |
Safe Output Mapping
| User says... |
Maps to |
| "post a comment" |
add-comment |
| "create an issue" |
create-issue |
| "update issue title/body" |
update-issue |
| "close the issue" |
close-issue |
| "assign someone", "remove assignment" |
assign-to-user, unassign-from-user |
| "set issue type/field/milestone" |
set-issue-type, set-issue-field, assign-milestone |
| "open a PR", "submit changes" |
create-pull-request |
| "update PR description/title" |
update-pull-request |
| "close the PR", "merge the PR" |
close-pull-request, merge-pull-request |
| "mark PR ready", "sync PR branch" |
mark-pull-request-as-ready-for-review, update-branch |
| "commit a fix to the PR branch" |
push-to-pull-request-branch |
| "approve / request changes" |
submit-pull-request-review |
| "inline review comment", "reply to review thread" |
create-pull-request-review-comment, reply-to-pull-request-review-comment, resolve-pull-request-review-thread |
| "start or edit discussion", "close discussion" |
create-discussion, update-discussion, close-discussion |
| "request reviewer", "hide comment" |
add-reviewer, hide-comment |
| "create/update project", "project status update" |
create-project, update-project, create-project-status-update |
| "update release", "upload release asset" |
update-release, upload-asset |
| "create/auto-fix code scan alert" |
create-code-scanning-alert, autofix-code-scanning-alert |
| "start an agent session", "assign to an agent" |
create-agent-session, assign-to-agent |
| "store persistent memory comment" |
comment-memory |
| "link a sub-issue" |
link-sub-issue |
| "add labels", "remove labels" |
add-labels, remove-labels |
| "nothing visible", "just analyze" |
no safe outputs required |
Network Mapping
| User says... |
Maps to |
| "calls an external API" |
ask for exact FQDN/wildcard, then add to network.allowed |
| "reads GitHub data / clones repos" |
include github in network.allowed |
| "uses GitHub Actions artifacts or cache" |
include github-actions in network.allowed |
| "installs npm packages" |
include node in network.allowed |
| "runs pip install" |
include python in network.allowed |
| "builds Go code" |
include go in network.allowed |
| "installs gems / uses Bundler" |
include ruby in network.allowed |
| "runs cargo build" |
include rust in network.allowed |
| "uses NuGet / .NET restore" |
include dotnet in network.allowed |
| "builds with Maven / Gradle" |
include java in network.allowed |
| "uses Docker / pulls container images / pushes to GHCR" |
include containers in network.allowed |
| "runs Playwright browser tests" |
include playwright in network.allowed |
| "runs apt install / yum / apk" |
include linux-distros in network.allowed |
| "uses Terraform / HashiCorp registry" |
include terraform in network.allowed |
| "connects to localhost / loopback / local services" |
include local in network.allowed |
| "uses Swift Package Manager" |
include swift in network.allowed |
| "uses Composer / PHP packages" |
include php in network.allowed |
| "uses pub.dev / Dart packages" |
include dart in network.allowed |
| "uses Hackage / Haskell packages" |
include haskell in network.allowed |
| "uses CPAN / Perl packages" |
include perl in network.allowed |
| "serves or loads web fonts" |
include fonts in network.allowed |
| "uses Deno or JSR packages" |
include deno in network.allowed |
| "uses Elixir / Hex packages" |
include elixir in network.allowed |
| "uses Bazel build" |
include bazel in network.allowed |
| "uses R / CRAN packages" |
include r in network.allowed |
| "no external access" |
network.allowed: [defaults] (or [] if explicitly zero network) |
Tool Mapping
| User says... |
Maps to |
| "read GitHub issues/PRs/workflows" |
tools.github with mode: gh-proxy and minimal toolsets |
| "use full MCP server/tool definitions" |
tools.github with mode: local |
| "use other MCP servers but keep token cost down" |
tools.cli-proxy: true (hybrid CLI-proxy mode) |
| "edit files" |
edit tool (default unless restricted) |
| "run commands/tests" |
bash tool (default unless restricted) |
| "browse web pages/docs" |
web-fetch and/or web-search |
| "test UI flows" |
playwright |
Pattern Heuristics
| User says... |
Recommended named pattern |
| "triage issues automatically" |
IssueOps |
| "run on /commands with human approval loops" |
ChatOps |
| "run every weekday and keep improving" |
DailyOps |
| "monitor workflow failures and trends" |
MonitorOps |
| "process a big backlog in chunks" |
BatchOps |
| "run manually with input parameters" |
DispatchOps |
| "apply a label-based workflow" |
LabelOps |
| "operate across multiple repositories" |
MultiRepoOps |
| "coordinate multiple sub-agents" |
Orchestration |
| "manage project board items" |
ProjectOps |
| "research, plan, and assign issues" |
ResearchPlanAssignOps |
| "self-correcting / retry on failure" |
CorrectionOps |
| "run in a side/fork repo" |
SideRepoOps |
| "write a spec before implementing" |
SpecOps |
| "A/B test workflow variants" |
TrialOps |
| "process items from a queue" |
WorkQueueOps |
| "deterministic, no LLM needed" |
DeterministicOps |
| "manage from a central repo" |
CentralRepoOps |
| "track work via GitHub Projects" |
Monitoring with Projects |
Integration Auth Mapping
When the user names a third-party service or MCP server:
- Confirm whether native tool, MCP server, or safe-output job is the right integration path.
- Look up the integration's auth requirements and required scopes before finalizing the design.
- Provide a concrete setup checklist with:
- required GitHub Actions secrets (names to create)
- workflow env variables that consume those secrets
- minimum token scopes/permissions needed
Output format to use:
Integration auth setup:
- <service-or-mcp>: <purpose>
- Secrets to create: <SECRET_NAME>, <SECRET_NAME>
- Workflow env vars: <ENV_VAR>=${{ secrets.<SECRET_NAME> }}
- Required scopes/permissions: <least-privilege scopes>
Never suggest committing plaintext tokens.
Data Strategy Mapping
| User says... |
Maps to |
| "analyze PRs", "review issues", "check status" |
add steps: that pre-fetch with gh + jq |
| "read the diff", "look at changed files" |
add steps: using gh pr diff or gh pr view --json files |
| "search for patterns across repos" |
add steps: using gh search + jq filters |
| "just respond to a comment" |
no pre-fetch needed (event payload is enough) |
| "process each item individually" |
suggest sub-agent pattern with model: small |
Token Optimization Defaults
Apply these defaults unless the user explicitly asks otherwise:
- Use DataOps by default for GitHub reads: pre-fetch/aggregate with
gh + jq in steps:, store compact JSON in /tmp/gh-aw/data/, and point the prompt to those files (see .github/aw/token-optimization.md for details).
- Keep tool surface minimal: default to
tools.github.mode: gh-proxy, include only required toolsets, and prefer bash + gh for simple reads.
- For batch workloads, split items into compact data and suggest sub-agent processing with
model: small.
- Keep prompts compact: concise imperative instructions, explicit file paths, single-line
noop guidance, and stable instructions before dynamic content.
Progressive Disclosure Rules
- Never dump all options at once; ask one targeted question at a time.
- Skip questions when answers are inferable from prior user statements.
- Offer smart defaults and request confirmation instead of over-questioning.
- Ask at most 5 questions before presenting a summary; then ask "anything else?" if needed.
- Detect done signals (
that's it, looks good, generate it) and proceed to generation.
Confirmation Format
Use this exact structure:
📋 Proposed workflow:
- Name: <workflow-id>
- Trigger: <event + key options>
- Engine: <engine or default>
- Tools: <tool summary>
- Safe outputs: <list or none>
- Network: <allowed summary>
- Integrations/Auth: <service/mcp + required secrets/env vars>
- Deployment: <GitHub.com or GHEC/GHES details>
- Intent: <one-sentence task>
Then ask: "Ready to generate, or want to adjust anything?"
Generation Template
After confirmation, generate one workflow file using the same skeleton style as .github/aw/create-agentic-workflow.md.
---
emoji: <emoji>
description: <brief description>
on:
<trigger config>
permissions:
contents: read
issues: read
pull-requests: read
tools:
github:
mode: gh-proxy
toolsets: [default]
steps:
- name: <optional data prefetch>
run: |
mkdir -p /tmp/gh-aw/data
<gh + jq commands that produce compact JSON>
safe-outputs:
<safe-output-types-if-needed>
network:
allowed:
- defaults
- <additional entries if needed>
---
# <Workflow Name>
## Task
<clear instructions tied to trigger context>
If `steps:` includes pre-fetch commands, read the resulting `/tmp/gh-aw/data/*.json` files instead of broad live re-fetches.
## Safe Outputs
- Use configured safe outputs for all visible write actions.
- Call `noop` with a short reason when no action is needed.
Validation Checklist
Before final output, run this internal self-check:
References (load only when needed)
In-repo references:
.github/aw/syntax.md (index → .github/aw/syntax-core.md, .github/aw/syntax-agentic.md, .github/aw/syntax-tools-imports.md)
.github/aw/safe-outputs.md (index → .github/aw/safe-outputs-content.md, .github/aw/safe-outputs-management.md, .github/aw/safe-outputs-automation.md, .github/aw/safe-outputs-runtime.md)
.github/aw/network.md
.github/aw/patterns.md
.github/aw/subagents.md
.github/aw/token-optimization.md
.github/aw/triggers.md
.github/aw/create-agentic-workflow.md
Portable HTTPS references:
https://github.com/github/gh-aw/blob/main/.github/aw/syntax.md (index → .../syntax-core.md, .../syntax-agentic.md, .../syntax-tools-imports.md)
https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs.md (index → .../safe-outputs-content.md, .../safe-outputs-management.md, .../safe-outputs-automation.md, .../safe-outputs-runtime.md)
https://github.com/github/gh-aw/blob/main/.github/aw/network.md
https://github.com/github/gh-aw/blob/main/.github/aw/patterns.md
https://github.com/github/gh-aw/blob/main/.github/aw/triggers.md
https://github.com/github/gh-aw/blob/main/.github/aw/create-agentic-workflow.md
1---2name: agentic-workflow-designer3description: Conversational skill that interviews users to design new agentic workflows4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/z3prover/agentic-workflow-designer7---89# Workflow Designer1011Use this skill to run a structured interview with users who know their goal but not the workflow syntax yet, then generate one complete workflow `.md` file.1213## When to Use This Skill1415Use this before `.github/aw/create-agentic-workflow.md` when requirements are unclear or incomplete.1617- Use `skills/agentic-workflow-designer/SKILL.md` to discover and confirm requirements.18- Use `.github/aw/create-agentic-workflow.md` once requirements are clear and ready for implementation.19- Use `.github/aw/agentic-chat.md` when the user wants a specification/pseudo-code instead of a runnable workflow file.2021## Interview Framework2223Ask one question at a time. Move to the next phase only after the current phase is clear.2425### Phase 1: Goal2627Ask: **"What do you want to automate?"**2829Capture:30- Workflow name (kebab-case candidate)31- Brief description32- Optional emoji3334### Phase 2: Trigger3536Ask: **"When should this run?"**3738Follow up only if needed:39- Which event type(s)?40- Any filters (labels, branches, commands)?41- Scheduled cadence (daily/weekly/hourly)?4243Map to the `on:` block.4445### Phase 3: Scope (Read/Write)4647Ask:48- **"What should it read?"** (issues, PRs, code, discussions, CI data)49- **"What should it create or update?"** (comments, issues, PRs, labels)5051Map to:52- `permissions:` (keep read-only for agent job)53- `tools:`54- `safe-outputs:`5556### Phase 4: Data Strategy5758Ask:59- **"What data does the agent need to make decisions?"**60- Follow up: **"Can we pre-fetch and aggregate that data with shell commands so the agent only reads compact JSON?"**6162Capture:63- Whether `steps:` should pre-fetch GitHub data with `gh` + `jq`64- Output paths under `/tmp/gh-aw/data/`65- Whether batch work should use sub-agents6667Map to:68- `steps:`69- Prompt references to pre-computed file paths7071### Phase 5: Guardrails7273Ask: **"Should it block merging, just advise, or silently log?"**7475Capture:76- Visibility expectations (comment, issue, no visible output)77- No-op behavior expectation7879Guide toward safe output behavior and explicit `noop` instructions.8081### Phase 6: Context & Network8283Ask: **"Does it need external APIs, web access, package installs, or MCP servers?"**8485Follow up:86- **"Any third-party services or MCP servers to include (for example Slack, Jira, Datadog, custom internal MCP)?"**87- **"Are you deploying on GitHub.com, GHEC with custom endpoints, or GHES?"**88- For each integration, identify required auth from source docs and map it to GitHub Actions secrets + workflow env variables.89- Ask for exact external domains (FQDN/wildcard).9091Map to:92- `network.allowed`93- Optional MCP/GitHub tool usage in `tools:`94- `secrets:` / `env:` wiring for integration tokens95- GHES/GHEC settings such as `engine.api-target` and `aw.json` `ghes: true` (when applicable)9697### Phase 7: Engine (optional)9899Ask only if ambiguous: **"Any AI engine preference?"**100101If no preference, suggest default:102- "I'd suggest Copilot since you haven't mentioned a preference. Sound good?"103104Map to `engine:` only when not default.105106### Phase 8: Confirmation107108Present a structured summary and ask for approval before generation.109110## Decision Heuristics111112### Trigger Mapping113114| User says... | Maps to |115|---|---|116| "when someone opens a PR" | `on: pull_request:` with `types: [opened]` |117| "when a PR is updated" | `on: pull_request:` with `types: [opened, synchronize]` |118| "every morning", "daily" | fuzzy schedule shorthand `on: schedule: daily on weekdays` (compiler expands to cron) |119| "every Monday", "weekly" | fuzzy schedule shorthand `on: schedule: weekly` (compiler expands to cron) |120| "when I say /review" | `on: slash_command:` with `name: review` (or requested command) |121| "when an issue is labeled bug" | `on: issues:` with `types: [labeled]` and label filter guidance |122| "run when label ai-review is added" | `on: label_command:` with `name`/`names`, optional event scoping, and label-as-command semantics |123| "run on PRs from forks" | `on: pull_request:` plus explicit `forks:` allowlist and fork security guardrails |124| "sometimes automatic, sometimes manual" | semi-active pattern: combine `schedule`/event triggers with `workflow_dispatch` |125| "manually", "on demand" | `on: workflow_dispatch:` |126| "when a deployment fails" | `on: deployment_status:` |127| "when another workflow finishes" | `on: workflow_run:` |128129### Safe Output Mapping130131| User says... | Maps to |132|---|---|133| "post a comment" | `add-comment` |134| "create an issue" | `create-issue` |135| "update issue title/body" | `update-issue` |136| "close the issue" | `close-issue` |137| "assign someone", "remove assignment" | `assign-to-user`, `unassign-from-user` |138| "set issue type/field/milestone" | `set-issue-type`, `set-issue-field`, `assign-milestone` |139| "open a PR", "submit changes" | `create-pull-request` |140| "update PR description/title" | `update-pull-request` |141| "close the PR", "merge the PR" | `close-pull-request`, `merge-pull-request` |142| "mark PR ready", "sync PR branch" | `mark-pull-request-as-ready-for-review`, `update-branch` |143| "commit a fix to the PR branch" | `push-to-pull-request-branch` |144| "approve / request changes" | `submit-pull-request-review` |145| "inline review comment", "reply to review thread" | `create-pull-request-review-comment`, `reply-to-pull-request-review-comment`, `resolve-pull-request-review-thread` |146| "start or edit discussion", "close discussion" | `create-discussion`, `update-discussion`, `close-discussion` |147| "request reviewer", "hide comment" | `add-reviewer`, `hide-comment` |148| "create/update project", "project status update" | `create-project`, `update-project`, `create-project-status-update` |149| "update release", "upload release asset" | `update-release`, `upload-asset` |150| "create/auto-fix code scan alert" | `create-code-scanning-alert`, `autofix-code-scanning-alert` |151| "start an agent session", "assign to an agent" | `create-agent-session`, `assign-to-agent` |152| "store persistent memory comment" | `comment-memory` |153| "link a sub-issue" | `link-sub-issue` |154| "add labels", "remove labels" | `add-labels`, `remove-labels` |155| "nothing visible", "just analyze" | no safe outputs required |156157### Network Mapping158159| User says... | Maps to |160|---|---|161| "calls an external API" | ask for exact FQDN/wildcard, then add to `network.allowed` |162| "reads GitHub data / clones repos" | include `github` in `network.allowed` |163| "uses GitHub Actions artifacts or cache" | include `github-actions` in `network.allowed` |164| "installs npm packages" | include `node` in `network.allowed` |165| "runs pip install" | include `python` in `network.allowed` |166| "builds Go code" | include `go` in `network.allowed` |167| "installs gems / uses Bundler" | include `ruby` in `network.allowed` |168| "runs cargo build" | include `rust` in `network.allowed` |169| "uses NuGet / .NET restore" | include `dotnet` in `network.allowed` |170| "builds with Maven / Gradle" | include `java` in `network.allowed` |171| "uses Docker / pulls container images / pushes to GHCR" | include `containers` in `network.allowed` |172| "runs Playwright browser tests" | include `playwright` in `network.allowed` |173| "runs apt install / yum / apk" | include `linux-distros` in `network.allowed` |174| "uses Terraform / HashiCorp registry" | include `terraform` in `network.allowed` |175| "connects to localhost / loopback / local services" | include `local` in `network.allowed` |176| "uses Swift Package Manager" | include `swift` in `network.allowed` |177| "uses Composer / PHP packages" | include `php` in `network.allowed` |178| "uses pub.dev / Dart packages" | include `dart` in `network.allowed` |179| "uses Hackage / Haskell packages" | include `haskell` in `network.allowed` |180| "uses CPAN / Perl packages" | include `perl` in `network.allowed` |181| "serves or loads web fonts" | include `fonts` in `network.allowed` |182| "uses Deno or JSR packages" | include `deno` in `network.allowed` |183| "uses Elixir / Hex packages" | include `elixir` in `network.allowed` |184| "uses Bazel build" | include `bazel` in `network.allowed` |185| "uses R / CRAN packages" | include `r` in `network.allowed` |186| "no external access" | `network.allowed: [defaults]` (or `[]` if explicitly zero network) |187188### Tool Mapping189190| User says... | Maps to |191|---|---|192| "read GitHub issues/PRs/workflows" | `tools.github` with `mode: gh-proxy` and minimal `toolsets` |193| "use full MCP server/tool definitions" | `tools.github` with `mode: local` |194| "use other MCP servers but keep token cost down" | `tools.cli-proxy: true` (hybrid CLI-proxy mode) |195| "edit files" | `edit` tool (default unless restricted) |196| "run commands/tests" | `bash` tool (default unless restricted) |197| "browse web pages/docs" | `web-fetch` and/or `web-search` |198| "test UI flows" | `playwright` |199200### Pattern Heuristics201202| User says... | Recommended named pattern |203|---|---|204| "triage issues automatically" | `IssueOps` |205| "run on /commands with human approval loops" | `ChatOps` |206| "run every weekday and keep improving" | `DailyOps` |207| "monitor workflow failures and trends" | `MonitorOps` |208| "process a big backlog in chunks" | `BatchOps` |209| "run manually with input parameters" | `DispatchOps` |210| "apply a label-based workflow" | `LabelOps` |211| "operate across multiple repositories" | `MultiRepoOps` |212| "coordinate multiple sub-agents" | `Orchestration` |213| "manage project board items" | `ProjectOps` |214| "research, plan, and assign issues" | `ResearchPlanAssignOps` |215| "self-correcting / retry on failure" | `CorrectionOps` |216| "run in a side/fork repo" | `SideRepoOps` |217| "write a spec before implementing" | `SpecOps` |218| "A/B test workflow variants" | `TrialOps` |219| "process items from a queue" | `WorkQueueOps` |220| "deterministic, no LLM needed" | `DeterministicOps` |221| "manage from a central repo" | `CentralRepoOps` |222| "track work via GitHub Projects" | `Monitoring with Projects` |223224### Integration Auth Mapping225226When the user names a third-party service or MCP server:2272281. Confirm whether native tool, MCP server, or safe-output job is the right integration path.2292. Look up the integration's auth requirements and required scopes before finalizing the design.2303. Provide a concrete setup checklist with:231 - required GitHub Actions secrets (names to create)232 - workflow env variables that consume those secrets233 - minimum token scopes/permissions needed234235Output format to use:236237```text238Integration auth setup:239- <service-or-mcp>: <purpose>240 - Secrets to create: <SECRET_NAME>, <SECRET_NAME>241 - Workflow env vars: <ENV_VAR>=${{ secrets.<SECRET_NAME> }}242 - Required scopes/permissions: <least-privilege scopes>243```244245Never suggest committing plaintext tokens.246247### Data Strategy Mapping248249| User says... | Maps to |250|---|---|251| "analyze PRs", "review issues", "check status" | add `steps:` that pre-fetch with `gh` + `jq` |252| "read the diff", "look at changed files" | add `steps:` using `gh pr diff` or `gh pr view --json files` |253| "search for patterns across repos" | add `steps:` using `gh search` + `jq` filters |254| "just respond to a comment" | no pre-fetch needed (event payload is enough) |255| "process each item individually" | suggest sub-agent pattern with `model: small` |256257## Token Optimization Defaults258259Apply these defaults unless the user explicitly asks otherwise:2602611. Use DataOps by default for GitHub reads: pre-fetch/aggregate with `gh` + `jq` in `steps:`, store compact JSON in `/tmp/gh-aw/data/`, and point the prompt to those files (see `.github/aw/token-optimization.md` for details).2622. Keep tool surface minimal: default to `tools.github.mode: gh-proxy`, include only required toolsets, and prefer `bash` + `gh` for simple reads.2633. For batch workloads, split items into compact data and suggest sub-agent processing with `model: small`.2644. Keep prompts compact: concise imperative instructions, explicit file paths, single-line `noop` guidance, and stable instructions before dynamic content.265266## Progressive Disclosure Rules2672681. Never dump all options at once; ask one targeted question at a time.2692. Skip questions when answers are inferable from prior user statements.2703. Offer smart defaults and request confirmation instead of over-questioning.2714. Ask at most 5 questions before presenting a summary; then ask "anything else?" if needed.2725. Detect done signals (`that's it`, `looks good`, `generate it`) and proceed to generation.273274## Confirmation Format275276Use this exact structure:277278```text279📋 Proposed workflow:280- Name: <workflow-id>281- Trigger: <event + key options>282- Engine: <engine or default>283- Tools: <tool summary>284- Safe outputs: <list or none>285- Network: <allowed summary>286- Integrations/Auth: <service/mcp + required secrets/env vars>287- Deployment: <GitHub.com or GHEC/GHES details>288- Intent: <one-sentence task>289```290291Then ask: **"Ready to generate, or want to adjust anything?"**292293## Generation Template294295After confirmation, generate one workflow file using the same skeleton style as `.github/aw/create-agentic-workflow.md`.296297```markdown298---299emoji: <emoji>300description: <brief description>301on:302 <trigger config>303permissions:304 contents: read305 issues: read306 pull-requests: read307tools:308 github:309 mode: gh-proxy310 toolsets: [default]311steps:312 - name: <optional data prefetch>313 run: |314 mkdir -p /tmp/gh-aw/data315 <gh + jq commands that produce compact JSON>316safe-outputs:317 <safe-output-types-if-needed>318network:319 allowed:320 - defaults321 - <additional entries if needed>322---323324# <Workflow Name>325326## Task327328<clear instructions tied to trigger context>329If `steps:` includes pre-fetch commands, read the resulting `/tmp/gh-aw/data/*.json` files instead of broad live re-fetches.330331## Safe Outputs332333- Use configured safe outputs for all visible write actions.334- Call `noop` with a short reason when no action is needed.335```336337## Validation Checklist338339Before final output, run this internal self-check:340341- [ ] Agent job permissions remain read-only (writes only via safe outputs)342- [ ] `safe-outputs:` covers every write action mentioned in prompt/instructions343- [ ] Network access is scoped; avoid blanket wildcard entries344- [ ] Trigger matches the user's intended activation event345- [ ] Prompt instructs agent to call `noop` when no action is needed346- [ ] Unnecessary defaults are omitted (for example `engine: copilot`)347- [ ] If reading GitHub data, `steps:` pre-fetches compact JSON (DataOps)348- [ ] `tools.github.mode` is `gh-proxy` unless broader MCP toolsets are explicitly needed349- [ ] Only required toolsets are listed (avoid blanket toolset lists)350- [ ] Prompt references specific pre-computed file paths351- [ ] For batch processing (>5 items), sub-agent pattern is suggested352- [ ] For each third-party service/MCP integration, required secrets/env vars are listed353- [ ] Auth guidance includes least-privilege token scope recommendations354- [ ] For GHEC/GHES deployments, `engine.api-target` and GHES compatibility guidance are included when needed355356## References (load only when needed)357358In-repo references:359- `.github/aw/syntax.md` (index → `.github/aw/syntax-core.md`, `.github/aw/syntax-agentic.md`, `.github/aw/syntax-tools-imports.md`)360- `.github/aw/safe-outputs.md` (index → `.github/aw/safe-outputs-content.md`, `.github/aw/safe-outputs-management.md`, `.github/aw/safe-outputs-automation.md`, `.github/aw/safe-outputs-runtime.md`)361- `.github/aw/network.md`362- `.github/aw/patterns.md`363- `.github/aw/subagents.md`364- `.github/aw/token-optimization.md`365- `.github/aw/triggers.md`366- `.github/aw/create-agentic-workflow.md`367368Portable HTTPS references:369- `https://github.com/github/gh-aw/blob/main/.github/aw/syntax.md` (index → `.../syntax-core.md`, `.../syntax-agentic.md`, `.../syntax-tools-imports.md`)370- `https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs.md` (index → `.../safe-outputs-content.md`, `.../safe-outputs-management.md`, `.../safe-outputs-automation.md`, `.../safe-outputs-runtime.md`)371- `https://github.com/github/gh-aw/blob/main/.github/aw/network.md`372- `https://github.com/github/gh-aw/blob/main/.github/aw/patterns.md`373- `https://github.com/github/gh-aw/blob/main/.github/aw/triggers.md`374- `https://github.com/github/gh-aw/blob/main/.github/aw/create-agentic-workflow.md`