Add portable agentic-workflow-designer skill, route workflow-design requests through agentic-workflows dispatcher, bake in token-efficient design defaults, include designer skill in init output, and add integration auth/GHE guidance
#36748
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,307 @@ | ||
| --- | ||
| name: agentic-workflow-designer | ||
| description: Conversational skill that interviews users to design new agentic workflows | ||
| disable-model-invocation: true | ||
| --- | ||
|
|
||
| # 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. | ||
|
Contributor
There was a problem hiding this comment. Consider linking to the create-agentic-workflow doc here for discoverability. |
||
|
|
||
| - 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?" | ||
|
|
||
|
lpcox marked this conversation as resolved.
|
||
| 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 | | ||
| | "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` | | ||
| | "open a PR", "submit changes" | `create-pull-request` | | ||
| | "add labels" | `add-labels` | | ||
| | "remove labels" | `remove-labels` | | ||
|
Contributor
There was a problem hiding this comment. [/grill-with-docs] The A user following this guidance literally would produce an invalid config. 💡 Suggested fixMap to concrete hostnames or reference | "installs npm packages" | add `registry.npmjs.org` to `network.allowed` (see `.github/aw/network.md`) |
| "runs pip install" | add `pypi.org`, `files.pythonhosted.org` to `network.allowed` |
| "builds Go code" | add `proxy.golang.org`, `sum.golang.org` to `network.allowed` | |
||
| | "close the issue" | `close-issue` | | ||
| | "assign someone" | `assign-to-user` | | ||
| | "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` | | ||
| | "installs npm packages" | include `node` in `network.allowed` | | ||
| | "runs pip install" | include `python` in `network.allowed` | | ||
| | "builds Go code" | include `go` 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` | | ||
| | "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` | | ||
|
|
||
| ### Integration Auth Mapping | ||
|
|
||
| When the user names a third-party service or MCP server: | ||
|
|
||
| 1. Confirm whether native tool, MCP server, or safe-output job is the right integration path. | ||
| 2. Look up the integration's auth requirements and required scopes before finalizing the design. | ||
| 3. 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: | ||
|
|
||
| ```text | ||
| 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: | ||
|
|
||
| 1. 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). | ||
| 2. Keep tool surface minimal: default to `tools.github.mode: gh-proxy`, include only required toolsets, and prefer `bash` + `gh` for simple reads. | ||
| 3. For batch workloads, split items into compact data and suggest sub-agent processing with `model: small`. | ||
| 4. Keep prompts compact: concise imperative instructions, explicit file paths, single-line `noop` guidance, and stable instructions before dynamic content. | ||
|
|
||
| ## Progressive Disclosure Rules | ||
|
|
||
| 1. Never dump all options at once; ask one targeted question at a time. | ||
| 2. Skip questions when answers are inferable from prior user statements. | ||
| 3. Offer smart defaults and request confirmation instead of over-questioning. | ||
|
Contributor
There was a problem hiding this comment. [/grill-with-docs] Progressive Disclosure Rule 4 says "ask at most 5 questions before presenting a summary", but the Interview Framework defines 7 phases — meaning the rule is already violated before any follow-ups are asked. Either raise the cap to match the phase count (e.g., "ask at most 7–8 questions"), or restructure the phases so that multi-topic phases (e.g., Goal + Trigger) can be collapsed into fewer turns. |
||
| 4. Ask at most 5 questions before presenting a summary; then ask "anything else?" if needed. | ||
| 5. Detect done signals (`that's it`, `looks good`, `generate it`) and proceed to generation. | ||
|
|
||
| ## Confirmation Format | ||
|
|
||
| Use this exact structure: | ||
|
|
||
| ```text | ||
| 📋 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> | ||
| ``` | ||
|
Contributor
There was a problem hiding this comment. [/grill-with-docs] The generation template doesn't include the An agent following this skill will ask about engine preference, collect the answer, and then silently drop it when filling in the template. 💡 Suggested additionAdd a conditional comment in the template so the agent knows when to emit it: # engine: <value> # omit entirely when using the default Copilot engineAlternatively, add a validation checklist item: "If non-default engine was confirmed, |
||
|
|
||
| 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`. | ||
|
|
||
| ```markdown | ||
| --- | ||
| 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> | ||
| --- | ||
|
|
||
|
lpcox marked this conversation as resolved.
|
||
| # <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: | ||
|
|
||
| - [ ] Agent job permissions remain read-only (writes only via safe outputs) | ||
| - [ ] `safe-outputs:` covers every write action mentioned in prompt/instructions | ||
| - [ ] Network access is scoped; avoid blanket wildcard entries | ||
| - [ ] Trigger matches the user's intended activation event | ||
| - [ ] Prompt instructs agent to call `noop` when no action is needed | ||
| - [ ] Unnecessary defaults are omitted (for example `engine: copilot`) | ||
| - [ ] If reading GitHub data, `steps:` pre-fetches compact JSON (DataOps) | ||
| - [ ] `tools.github.mode` is `gh-proxy` unless broader MCP toolsets are explicitly needed | ||
| - [ ] Only required toolsets are listed (avoid blanket toolset lists) | ||
| - [ ] Prompt references specific pre-computed file paths | ||
| - [ ] For batch processing (>5 items), sub-agent pattern is suggested | ||
| - [ ] For each third-party service/MCP integration, required secrets/env vars are listed | ||
| - [ ] Auth guidance includes least-privilege token scope recommendations | ||
| - [ ] For GHEC/GHES deployments, `engine.api-target` and GHES compatibility guidance are included when needed | ||
|
|
||
| ## References (load only when needed) | ||
|
|
||
| In-repo references: | ||
| - `.github/aw/syntax.md` | ||
| - `.github/aw/safe-outputs.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` | ||
| - `https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs.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` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice clear title heading for the skill. 👍