Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/aw/github-agentic-workflows.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

36 changes: 24 additions & 12 deletions .github/aw/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,35 @@ List available skills and their locations before deciding which strategy to appl

**Use when**: You want to keep the main prompt compact while still shipping task-specific skill guidance with the workflow.

Inline skills let a workflow embed a complete skill or a partial skill fragment under `## skill: \`name\``.
Extraction happens in the setup/interpolation runtime step of workflow execution, not at `.md` to `.lock.yml` compile time.
gh-aw writes each block into engine-specific skill locations and removes those blocks from the main prompt body.
This keeps the main prompt slim and flexible while still making the fused guidance available as skills.
Inline skills embed a skill block directly in the workflow markdown under `` ## skill: `name` ``. The block ends at the next `##` heading or end of file. The compiler strips inline skill sections from the effective markdown before include expansion (so they never appear in the main prompt), and the runtime extractor writes each block to an engine-specific skills directory after `{{#runtime-import}}` macros are resolved.

Use this to fuse:
The syntax and name rules mirror inline sub-agents — one mental model covers both.

- A full skill when the workflow needs a self-contained capability.
- Partial skill sections when only targeted guidance is needed.
### Frontmatter

**Pattern**:
Only the `description` field is supported. Any other top-level frontmatter key is stripped during extraction and a warning is logged.

### Name rules

- Must start with a lowercase letter (`a–z`)
- May contain only `a–z`, `0–9`, `_`, `-`
- Must be unique within a single workflow file — duplicates are a parse error

### Engine-specific output paths

| Engine | Path |
|---|---|
| `claude` | `.claude/skills/<name>.md` |
| `codex` | `.codex/skills/<name>.md` |
| `gemini` | `.gemini/skills/<name>.md` |
| other / unset (incl. `copilot`) | `.github/skills/<name>/SKILL.md` |

Avoid naming collisions with file-based skills already in the repository — inline extraction writes to the same engine skill paths.

### Pattern

```markdown
---
on:
workflow_dispatch:
engine: copilot
Expand All @@ -52,10 +68,6 @@ Classify by bug / feature / question, identify missing information, and suggest
the smallest actionable next step.
```

Use a unique inline skill name per workflow file. The name can be arbitrary, but it must start with a lowercase letter and then use only lowercase letters, digits, `_`, or `-`.
These constraints keep extracted skill paths predictable and engine-compatible.
Avoid naming collisions with repository file-based skills (for example `.github/skills/<name>/SKILL.md`), because inline extraction writes to the same engine skill paths.

---

## Strategy 1 — Hint (Generalist)
Expand Down