diff --git a/.github/aw/upgrade-agentic-workflows.md b/.github/aw/upgrade-agentic-workflows.md
index b05cb67671..b278e47797 100644
--- a/.github/aw/upgrade-agentic-workflows.md
+++ b/.github/aw/upgrade-agentic-workflows.md
@@ -23,15 +23,16 @@ Read the ENTIRE content of this file carefully before proceeding. Follow the ins
 - `compile` → compile all workflows
 - `compile <workflow-name>` → compile a specific workflow
 
-:::note[Command Execution]
-When running in GitHub Copilot Cloud, you don't have direct access to `gh aw` CLI commands. Instead, use the **agentic-workflows** MCP tool:
-- `fix` tool → apply automatic codemods to fix deprecated fields
-- `compile` tool → compile workflows
-
-When running in other environments with `gh aw` CLI access, prefix commands with `gh aw` (e.g., `gh aw compile`).
-
-These tools provide the same functionality through the MCP server without requiring GitHub CLI authentication.
-:::
+> [!NOTE]
+> **Command Execution**
+>
+> When running in GitHub Copilot Cloud, you don't have direct access to `gh aw` CLI commands. Instead, use the **agentic-workflows** MCP tool:
+> - `fix` tool → apply automatic codemods to fix deprecated fields
+> - `compile` tool → compile workflows
+>
+> When running in other environments with `gh aw` CLI access, prefix commands with `gh aw` (e.g., `gh aw compile`).
+>
+> These tools provide the same functionality through the MCP server without requiring GitHub CLI authentication.
 
 ## Instructions
 
diff --git a/AGENTS.md b/AGENTS.md
index 8727d717c4..a464c4cbd5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -583,7 +583,7 @@ When developing a new command:
 
 **Primary YAML Library**: `goccy/go-yaml` v1.19.1
 
-gh-aw uses `goccy/go-yaml` for YAML 1.1/1.2 compatibility with GitHub Actions. See <a>specs/yaml-version-gotchas.md</a> for details on YAML version differences.
+gh-aw uses `goccy/go-yaml` for YAML 1.1/1.2 compatibility with GitHub Actions. See [specs/yaml-version-gotchas.md](specs/yaml-version-gotchas.md) for details on YAML version differences.
 
 **Standard YAML Library**: `go.yaml.in/yaml/v3` v3.0.4
 
@@ -724,7 +724,7 @@ func ValidatePermissions(permissions *Permissions, githubTool any)
 - Large "god" interfaces with many methods
 - Type name collisions (use descriptive, domain-qualified names)
 
-**See**: <a>specs/go-type-patterns.md</a> for detailed guidance and examples
+**See**: [specs/go-type-patterns.md](specs/go-type-patterns.md) for detailed guidance and examples
 
 ### Frontmatter Configuration Types