diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md
index fae2da3d14b..875b02312c5 100644
--- a/.github/aw/github-agentic-workflows.md
+++ b/.github/aw/github-agentic-workflows.md
@@ -80,6 +80,7 @@ Always run `gh aw compile` after modifying frontmatter. Markdown body changes ta
 | Memory / persistence | [memory.md](memory.md) |
 | Experiments / A/B testing | [experiments.md](experiments.md) |
 | Campaign / KPI workflows | [campaign.md](campaign.md) |
+| Skills (inline + file-based) | [skills.md](skills.md) |
 | LLM API endpoint discovery | [llms.md](llms.md) |
 
 ## Key Principles
diff --git a/.github/aw/skills.md b/.github/aw/skills.md
index a55b65c9acf..be2ebdec824 100644
--- a/.github/aw/skills.md
+++ b/.github/aw/skills.md
@@ -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
@@ -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)