docs: add GHCR container auth requirement to skill references

- Add steps: frontmatter field docs with GHCR login pattern
- Add container authentication section to tools-reference
- Add silent container pull failure to validation errors, anti-patterns, and checklist
- Add critical rule #12 for GHCR login requirement

Author: zircote

skills/aw-author/SKILL.md

@@ -382,3 +382,4 @@ These rules apply across ALL modes:
 9. **All workflow-created items** include a hidden `<!-- gh-aw-workflow-id: NAME -->` marker
 10. **`read-all` permission shorthand** expands to read on all permission scopes
 11. **`event.json` fallback** — when `${{ github.event }}` is unavailable, agents should check for `event.json` in the workspace
+12. **Container-based MCP servers from `ghcr.io` require a GHCR login step** — add a `steps:` block with `docker login ghcr.io` using `${{ github.token }}` before `safe-outputs:`, or container pulls fail silently

skills/aw-author/references/frontmatter-schema.md

@@ -192,6 +192,38 @@ safe-outputs:
     append-only-comments: true
 ```
 
+## Steps (`steps:`)
+
+Pre-agent setup steps that run before the agentic workflow starts. These compile into GitHub Actions job steps that execute before the agent is invoked.
+
+```yaml
+steps:
+  - name: Login to GitHub Container Registry
+    run: echo "${{ github.token }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+```
+
+### When Steps Are Required
+
+**Container-based MCP servers pulling from ghcr.io require GHCR authentication.** Without a login step, container pulls fail silently at runtime. This is the most common cause of container-based workflow failures.
+
+If your workflow uses `mcp-servers:` with a `container:` field referencing `ghcr.io`, you **must** include a GHCR login step:
+
+```yaml
+mcp-servers:
+  my-server:
+    container: ghcr.io/org/image:latest
+    env:
+      TOKEN: "${{ secrets.VALUE }}"
+
+steps:
+  - name: Login to GitHub Container Registry
+    run: echo "${{ github.token }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+```
+
+The `steps:` block is placed after `mcp-servers:` (or after `tools:` if no MCP servers) and before `safe-outputs:`.
+
+---
+
 ## Network Configuration (`network:`)
 
 ```yaml

skills/aw-author/references/tools-reference.md

@@ -278,9 +278,28 @@ mcp-servers:
     allowed: ["send_message", "get_channel_history"]
 ```
 
+### Container Authentication (GHCR)
+
+**CRITICAL:** When using `container:` with images hosted on GitHub Container Registry (`ghcr.io`), you **must** add a GHCR login step in the `steps:` block. Without this, container pulls fail silently at runtime.
+
+```yaml
+mcp-servers:
+  datadog:
+    container: ghcr.io/org/datadog-mcp:latest
+    env:
+      DD_API_KEY: "${{ secrets.DD_API_KEY }}"
+
+steps:
+  - name: Login to GitHub Container Registry
+    run: echo "${{ github.token }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+```
+
+This applies to **all** container-based MCP servers pulling from `ghcr.io`, regardless of whether the image is public or private. The `github.token` is automatically available and has sufficient scope for package reads.
+
 ### Key Constraints
 
 - Tool declarations merge from imported components
 - GitHub App tokens auto-revoke after workflow completion
 - Lockdown mode auto-enables for public repos with custom tokens
 - The `registry` field is informational and doesn't affect execution
+- Container-based MCP servers from `ghcr.io` require a GHCR login step (see above)

skills/aw-author/references/validation.md

@@ -49,6 +49,7 @@ Occur during GitHub Actions execution.
 - **Bash command blocked:** Attempting a command not in the allowlist
 - **Network blocked:** External URL access when no `network` configuration
 - **MCP server connection failed:** Server not available, wrong args, missing env vars
+- **Container pull failed (silent):** Container-based MCP servers from `ghcr.io` fail silently if no GHCR login step is present. Add a `steps:` block with `docker login ghcr.io` using `${{ github.token }}`
 
 ### Permission Errors
 - **Token insufficient:** `GITHUB_TOKEN` lacks required scope
@@ -114,6 +115,7 @@ The workflow runs but produces incorrect or unexpected results.
 | No `close-older-issues` on reports | Issue accumulation | Enable auto-cleanup |
 | Overlapping triggers | Double-processing | Use distinct event types |
 | `container:` with non-Docker value | Compilation error | Use valid Docker image reference |
+| `container: ghcr.io/…` without GHCR login step | Silent runtime failure | Add `steps:` with `docker login ghcr.io` |
 
 ### Prose Anti-Patterns
 
@@ -150,6 +152,7 @@ When a workflow fails, check in this order:
 - [ ] Bash allowlist covers required commands
 - [ ] MCP servers have correct env vars and args
 - [ ] Network config allows required external domains
+- [ ] Container-based MCP servers from `ghcr.io` have a GHCR login step in `steps:`
 
 ### 4. Safe-Outputs
 - [ ] Every write operation in prose has a matching safe-output