@@ -151,7 +151,8 @@ Block form (tag on its own line) is recommended for readability.
 
 ```markdown
 {{#if experiments.skill_hint == "enabled" }}
-Check `skills/` for SKILL.md files relevant to this task and apply their guidance.
+Check `skills/` and `.github/skills/` for relevant `SKILL.md` files and apply
+their guidance.
 {{#endif}}
 ```
 
@@ -175,4 +176,3 @@ When `experiments:` is set in frontmatter, the selected variant is substituted i
 - **Fenced code blocks are preserved** — `{{#if}}` tags inside `` ``` `` blocks appear verbatim.
 - **No nested conditionals** — inner tags become literal text.
 - **Tags are stripped before the agent runs** — never visible in the final prompt.
-
@@ -198,7 +198,8 @@ experiments:
 
 ```markdown
 {{#if experiments.skill_hint == "enabled" }}
-Check `skills/` for SKILL.md files relevant to this task and apply their guidance.
+Check `skills/` and `.github/skills/` for relevant `SKILL.md` files and apply
+their guidance.
 {{#endif}}
 ```
 
 
@@ -1,5 +1,5 @@
 ---
-description: Guide for leveraging skills (SKILL.md files) in agentic workflows — hint, fusion, and inline fusion strategies
+description: Guide for using skills in agentic workflows — compiler-managed `skills:` installs plus hint, fusion, and inline strategies
 ---
 
 # Skills in Agentic Workflows
@@ -16,20 +16,31 @@ find "${GITHUB_WORKSPACE}" -name "SKILL.md" -maxdepth 6
 
 ---
 
-## Frontmatter `skills:` (SHA-Pinned Installs)
+## Frontmatter `skills:` (Preferred for External Skills)
 
-Declare external skills to install at activation time with the top-level `skills:` array. At activation, `gh aw` installs each via `gh skill install` and wires it into the engine — no manual vendoring.
+Declare external skills to install at activation time with the top-level `skills:` array.
+The compiler emits the activation steps, prepares the required `gh` support, installs each skill, and wires it into the engine.
+Do **not** add manual `gh` setup or `gh skill install` steps for this.
 
 ```yaml
 skills:
-  - owner/repo@<40-char-sha>              # repository-wide install
-  - owner/repo/skill/path@<40-char-sha>   # path-scoped install
-  - skill: owner/repo@<40-char-sha>       # object form: per-skill auth
-    github-token: ${{ secrets.SKILLS_TOKEN }}
+  # Shared auth via the workflow activation token
+  - mattpocock/skills/tdd@801dca688564c529fa84f247f64472520d9ebe28
+
+  # Per-skill token for a private skill repository
+  - skill: mattpocock/skills/diagnosing-bugs@801dca688564c529fa84f247f64472520d9ebe28
+    github-token: ${{ secrets.MATT_SKILLS_PAT || secrets.GITHUB_TOKEN }}
+
+  # Per-skill GitHub App credentials
+  - skill: mattpocock/skills/domain-modeling@801dca688564c529fa84f247f64472520d9ebe28
+    github-app:
+      client-id: ${{ vars.MATT_SKILLS_APP_CLIENT_ID }}
+      private-key: ${{ secrets.MATT_SKILLS_APP_PRIVATE_KEY }}
 ```
 
 - Static references must be pinned to a full 40-character lowercase commit SHA; `${{ ... }}` expressions are allowed in the ref position and resolved at runtime.
 - Object entries set per-skill auth via `github-token` or `github-app`.
+- Use `skills:` for external skill installs and `imports:` for prompt/context files you want merged into the workflow.
 
 Distinct from the prompt-side strategies below (hint / fusion / inline), which shape skill *content* into the prompt rather than installing packages.
 
@@ -51,7 +62,7 @@ After discovery:
 
 - Prefer repository-local skills when they satisfy the task.
 - Extract only the specific guidance you need; do not paste entire skills when a fragment is enough.
-- Do not install or enable returned resources automatically; that requires explicit user choice.
+- If the user chooses an external skill, add it to frontmatter `skills:` instead of adding manual install steps.
 
 ---
 
@@ -90,9 +101,9 @@ Use a unique inline skill name per workflow file. Name must start with a lowerca
 **Pattern**:
 
 ```markdown
-If the repository contains `SKILL.md` files under `skills/`, check which ones are
-relevant to this task. For each relevant skill, read its content and apply the
-guidance it provides.
+If the repository contains `SKILL.md` files under `skills/` or `.github/skills/`,
+check which ones are relevant to this task. For each relevant skill, read its
+content and apply the guidance it provides.
 ```
 
 ---
@@ -104,7 +115,7 @@ guidance it provides.
 **Pattern**:
 
 ```markdown
-<!-- gh-skill-fusion: skills/github-mcp-server/SKILL.md#authentication -->
+<!-- gh-skill-fusion: .github/skills/github-mcp-server/SKILL.md#authentication -->
 
 When calling GitHub MCP tools, use the pre-configured token already injected into the
 environment. Never prompt the user for credentials.
@@ -142,8 +153,9 @@ permissions:
 
 Triage the newly opened issue.
 
-If there are relevant skills under `skills/`, read them and apply their guidance.
-Focus on skills related to issue classification or project conventions.
+If there are relevant skills under `skills/` or `.github/skills/`, read them and
+apply their guidance. Focus on skills related to issue classification or project
+conventions.
 ```
 
 ---
@@ -165,7 +177,7 @@ permissions:
 
 Review the pull request for adherence to project conventions.
 
-<!-- Fused from skills/developer/SKILL.md#code-organization -->
+<!-- Fused from .github/skills/developer/SKILL.md#code-organization -->
 Prefer many smaller files grouped by functionality. Add new files for new features
 rather than extending existing ones. Keep validators under 300 lines; split when
 a single file covers more than one domain.