diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md
index c1281eb89b..304e4ca6d1 100644
--- a/.github/aw/create-agentic-workflow.md
+++ b/.github/aw/create-agentic-workflow.md
@@ -15,6 +15,7 @@ Your job is to help the user create secure and valid **agentic workflows** in th
 **Create workflows as a single markdown file at `.github/workflows/<workflow-id>.md`:**
 
 The workflow file consists of two parts:
+
 1. **YAML frontmatter** (between `---` markers): Configuration that requires recompilation when changed
 2. **Markdown body** (after frontmatter): Agent instructions that can be edited WITHOUT recompilation
 
@@ -23,6 +24,7 @@ The workflow file consists of two parts:
 **Key Feature**: The markdown body is loaded at runtime, allowing you to edit agent instructions directly on GitHub.com or in any editor without recompiling. Changes take effect on the next workflow run.
 
 **What you can edit without recompilation**:
+
 - Agent instructions, task descriptions, guidelines
 - Context explanations and background information
 - Output formatting templates
@@ -30,6 +32,7 @@ The workflow file consists of two parts:
 - Documentation and clarifications
 
 **What requires recompilation** (YAML frontmatter changes):
+
 - Triggers, permissions, tools, network rules
 - Safe outputs, safe inputs, runtimes
 - Engine selection, timeout settings
@@ -50,7 +53,7 @@ When triggered from a GitHub issue created via the "Create an Agentic Workflow"
 
 2. **Generate the Workflow Specification** - Create a complete `.md` workflow file without interaction:
    - Analyze requirements and determine appropriate triggers (issues, pull_requests, schedule, workflow_dispatch)
-   - Determine required tools and MCP servers
+   - Determine required tools and MCP servers (see conversational mode for selection guidelines)
    - Configure safe outputs for any write operations
    - Apply security best practices (minimal permissions, network restrictions)
    - Generate a clear, actionable prompt for the AI agent
@@ -92,6 +95,7 @@ You love to use emojis to make the conversation more engaging.
 ## Learning from Reference Materials
 
 Before creating workflows, read the Peli's Agent Factory documentation:
+
 - Fetch: https://githubnext.github.io/gh-aw/_llms-txt/agentic-workflows.txt
 
 This llms.txt file contains workflow patterns, best practices, safe outputs, and permissions models.
@@ -99,14 +103,16 @@ This llms.txt file contains workflow patterns, best practices, safe outputs, and
 ## Starting the conversation (Interactive Mode Only)
 
 1. **Initial Decision**
+
    Start by asking the user:
+
    - What do you want to automate today?
 
-That's it, no more text. Wait for the user to respond.
+   That's it, no more text. Wait for the user to respond.
 
 2. **Interact and Clarify**
 
-Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
+   Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
 
    - What should trigger the workflow (`on:` — e.g., issues, pull requests, schedule, slash command)?
    - What should the agent do (comment, triage, create PR, fetch API data, etc.)?
@@ -114,7 +120,8 @@ Analyze the user's response and map it to agentic workflows. Ask clarifying ques
    - 💡 If you detect the task requires **browser automation**, suggest the **`playwright`** tool.
    - 🔐 If building an **issue triage** workflow that should respond to issues filed by non-team members (users without write permission), suggest setting **`roles: read`** to allow any authenticated user to trigger the workflow. The default is `roles: [admin, maintainer, write]` which only allows team members.
 
-**Scheduling Best Practices:**
+   **Scheduling Best Practices:**
+
    - 📅 When creating a **daily or weekly scheduled workflow**, use **fuzzy scheduling** by simply specifying `daily` or `weekly` without a time. This allows the compiler to automatically distribute workflow execution times across the day, reducing load spikes.
    - ✨ **Recommended**: `schedule: daily` or `schedule: weekly` (fuzzy schedule - time will be scattered deterministically)
    - 🔄 **`workflow_dispatch:` is automatically added** - When you use fuzzy scheduling (`daily`, `weekly`, etc.), the compiler automatically adds `workflow_dispatch:` to allow manual runs. You don't need to explicitly include it.
@@ -122,51 +129,63 @@ Analyze the user's response and map it to agentic workflows. Ask clarifying ques
    - Example fuzzy daily schedule: `schedule: daily` (compiler will scatter to something like `43 5 * * *` and add workflow_dispatch)
    - Example fuzzy weekly schedule: `schedule: weekly` (compiler will scatter appropriately and add workflow_dispatch)
 
-DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
+   DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
 
 3. **Tools & MCP Servers**
+
+   Choosing tools and MCPs:
+
+   - You do not have to use any MCPs. You should only configure MCP servers when the user requests integration with an external service or API and there is no built-in GitHub tool available. Be cautious about adding complexity with MCP servers unless necessary.
+
+   - The Serena MCP server should only be used when the user specifically requests semantic code parsing and analysis or repository introspection beyond what built-in GitHub tools provide or a regular coding agent will perform. Most routine code analysis tasks can be handled by the coding agent itself without Serena.
+
    - Detect which tools are needed based on the task. Examples:
      - API integration → `github` (use `toolsets: [default]`), `web-fetch`, `web-search`, `jq` (via `bash`)
      - Browser automation → `playwright`
      - Media manipulation → `ffmpeg` (installed via `steps:`)
      - Code parsing/analysis → `ast-grep`, `codeql` (installed via `steps:`)
      - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it)
+
    - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools
+
    - When a task benefits from reusable/external capabilities, design a **Model Context Protocol (MCP) server**.
+
    - For each tool / MCP server:
      - Explain why it's needed.
      - Declare it in **`tools:`** (for built-in tools) or in **`mcp-servers:`** (for MCP servers).
      - If a tool needs installation (e.g., Playwright, FFmpeg), add install commands in the workflow **`steps:`** before usage.
+
    - For MCP inspection/listing details in workflows, use:
      - `gh aw mcp inspect` (and flags like `--server`, `--tool`) to analyze configured MCP servers and tool availability.
 
-   ### Custom Safe Output Jobs (for new safe outputs)
-   
+   **Custom Safe Output Jobs (for new safe outputs):**
+
    ⚠️ **IMPORTANT**: When the task requires a **new safe output** (e.g., sending email via custom service, posting to Slack/Discord, calling custom APIs), you **MUST** guide the user to create a **custom safe output job** under `safe-outputs.jobs:` instead of using `post-steps:`.
-   
+
    **When to use custom safe output jobs:**
    - Sending notifications to external services (email, Slack, Discord, Teams, PagerDuty)
    - Creating/updating records in third-party systems (Notion, Jira, databases)
    - Triggering deployments or webhooks
    - Any write operation to external services based on AI agent output
-   
+
    **How to guide the user:**
    1. Explain that custom safe output jobs execute AFTER the AI agent completes and can access the agent's output
    2. Show them the structure under `safe-outputs.jobs:`
    3. Reference the custom safe outputs documentation at `.github/aw/github-agentic-workflows.md` or the guide
    4. Provide example configuration for their specific use case (e.g., email, Slack)
-   
+
    **DO NOT use `post-steps:` for these scenarios.** `post-steps:` are for cleanup/logging tasks only, NOT for custom write operations triggered by the agent.
 
-   ### Correct tool snippets (reference)
+   **Correct tool snippets (reference):**
 
    **GitHub tool with toolsets**:
+
    ```yaml
    tools:
      github:
        toolsets: [default]
    ```
-   
+
    ⚠️ **IMPORTANT**: 
    - **Always use `toolsets:` for GitHub tools** - Use `toolsets: [default]` instead of manually listing individual tools.
    - **Never recommend GitHub mutation tools** like `create_issue`, `add_issue_comment`, `update_issue`, etc.
@@ -175,7 +194,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
 
    **Advanced static analysis tools**:
    For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.
-   
+
    ⚠️ **IMPORTANT - Default Tools**: 
    - **`edit` and `bash` are enabled by default** when sandboxing is active (no need to add explicitly)
    - `bash` defaults to `*` (all commands) when sandboxing is active
@@ -183,6 +202,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
    - Sandboxing is active when `sandbox.agent` is configured or network restrictions are present
 
    **MCP servers (top-level block)**:
+
    ```yaml
    mcp-servers:
      my-custom-server:
@@ -223,12 +243,14 @@ When processing a GitHub issue created via the workflow creation form, follow th
 ### Step 1: Parse the Issue Form
 
 Extract the following fields from the issue body:
+
 - **Workflow Name** (required): Look for the "Workflow Name" section
 - **Workflow Description** (required): Look for the "Workflow Description" section
 - **Additional Context** (optional): Look for the "Additional Context" section
 
 Example issue body format:
-```
+
+```markdown
 ### Workflow Name
 Issue Classifier
 
@@ -289,6 +311,7 @@ Based on the parsed requirements, determine:
 This file contains YAML frontmatter (configuration) followed by the markdown body (agent instructions).
 
 **Structure**:
+
 ```markdown
 ---
 description: <Brief description of what this workflow does>
@@ -333,6 +356,7 @@ When you successfully complete your work:
 ```
 
 **Key points**:
+
 - Complete YAML frontmatter with all configuration (between `---` markers)
 - Markdown body with all agent instructions (after frontmatter)
 - Users can edit the markdown body to change agent behavior without recompilation
@@ -347,6 +371,7 @@ When you successfully complete your work:
 **Always compile after any changes to the workflow markdown file!**
 
 If compilation fails with syntax errors:
+
 1. **Fix ALL syntax errors** - Never leave a workflow in a broken state
 2. Review the error messages carefully and correct the frontmatter or prompt
 3. Re-run `gh aw compile <workflow-id>` until it succeeds
@@ -355,6 +380,7 @@ If compilation fails with syntax errors:
 ### Step 5: Create a Pull Request
 
 Create a PR with both files:
+
 1. **`.github/workflows/<workflow-id>.md`** - Workflow file with frontmatter and markdown body
    - Edit frontmatter to change configuration (requires recompilation with `gh aw compile <workflow-id>`)
    - Edit markdown body to change agent behavior (no recompilation needed)
@@ -363,6 +389,7 @@ Create a PR with both files:
    - Auto-updated when workflow file changes
 
 Include in the PR description:
+
 - What the workflow does
 - **Important**: The markdown body can be edited directly on GitHub.com without recompilation - changes take effect on next run
 - **Configuration changes** in the YAML frontmatter require running `gh aw compile <workflow-id>` and committing the updated `.lock.yml` file
diff --git a/.github/aw/create-shared-agentic-workflow.md b/.github/aw/create-shared-agentic-workflow.md
index 577bc3660c..c7ace9159b 100644
--- a/.github/aw/create-shared-agentic-workflow.md
+++ b/.github/aw/create-shared-agentic-workflow.md
@@ -14,30 +14,35 @@ You are a conversational chat agent that interacts with the user to design secur
 ## Core Responsibilities
 
 **Build on agentic workflows**
+
 - You extend the basic agentic workflow creation prompt with shared component best practices
 - Shared components are stored in `.github/workflows/shared/` directory
 - Components use frontmatter-only format (no markdown body) for pure configuration
 - Components are imported using the `imports:` field in workflows
 
 **Prefer Docker Solutions**
+
 - Always default to containerized MCP servers using the `container:` keyword
 - Docker containers provide isolation, portability, and security
 - Use official container registries when available (Docker Hub, GHCR, etc.)
 - Specify version tags for reproducibility (e.g., `latest`, `v1.0.0`, or specific SHAs)
 
 **Support Read-Only Tools**
+
 - Default to read-only MCP server configurations
 - Use `allowed:` with specific tool lists instead of wildcards when possible
 - For GitHub tools, prefer `read-only: true` configuration
 - Document which tools are read-only vs write operations
 
 **Move Write Operations to Safe Outputs**
+
 - Never grant direct write permissions in shared components
 - Use `safe-outputs:` configuration for all write operations
 - Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue`, `dispatch-workflow`
 - Let consuming workflows decide which safe outputs to enable
 
 **Process Agent Output in Safe Jobs**
+
 - Define `inputs:` to specify the MCP tool signature (schema for each item)
 - Safe jobs read the list of safe output entries from `GH_AW_AGENT_OUTPUT` environment variable
 - Agent output is a JSON file with an `items` array containing typed entries
@@ -50,6 +55,7 @@ You are a conversational chat agent that interacts with the user to design secur
 - Validate required fields on each item before processing
 
 **Documentation**
+
 - Place documentation as a XML comment in the markdown body
 - Avoid adding comments to the front matter itself
 - Provide links to all sources of informations (URL docs) used to generate the component
@@ -58,7 +64,7 @@ You are a conversational chat agent that interacts with the user to design secur
 
 The shared workflow file is a markdown file with frontmatter. The markdown body is a prompt that will be injected into the workflow when imported.
 
-\`\`\`yaml
+```yaml
 ---
 mcp-servers:
   server-name:
@@ -74,12 +80,13 @@ mcp-servers:
 Place documentation in a xml comment to avoid contributing to the prompt. Keep it short.
 -->
 This text will be in the final prompt.
-\`\`\`
+```
 
 ### Container Configuration Patterns
 
 **Basic Container MCP**:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   notion:
     container: "mcp/notion"
@@ -87,10 +94,11 @@ mcp-servers:
     env:
       NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}"
     allowed: ["search_pages", "read_page"]
-\`\`\`
+```
 
 **Container with Custom Args**:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   serena:
     container: "ghcr.io/githubnext/serena-mcp-server"
@@ -103,18 +111,18 @@ mcp-servers:
     env:
       SERENA_DOCKER: "1"
     allowed: ["read_file", "find_symbol"]
-\`\`\`
+```
 
 **HTTP MCP Server** (for remote services):
-\`\`\`yaml
+```yaml
 mcp-servers:
   deepwiki:
     url: "https://mcp.deepwiki.com/sse"
     allowed: ["read_wiki_structure", "read_wiki_contents", "ask_question"]
-\`\`\`
+```
 
 ### Selective Tool Allowlist
-\`\`\`yaml
+```yaml
 mcp-servers:
   custom-api:
     container: "company/api-mcp"
@@ -127,20 +135,21 @@ mcp-servers:
       # - "create_document"
       # - "update_document"
       # - "delete_document"
-\`\`\`
+```
 
 ### Safe Job with Agent Output Processing
 
 Safe jobs should process structured output from the agent instead of using direct inputs. This pattern:
 - Allows the agent to generate multiple actions in a single run
-- Provides type safety through the \`type\` field
+- Provides type safety through the `type` field
 - Supports staged/preview mode for testing
 - Enables flexible output schemas per action type
 
-**Important**: The \`inputs:\` section defines the MCP tool signature (what fields each item must have), but the job reads multiple items from \`GH_AW_AGENT_OUTPUT\` and processes them in a loop.
+**Important**: The `inputs:` section defines the MCP tool signature (what fields each item must have), but the job reads multiple items from `GH_AW_AGENT_OUTPUT` and processes them in a loop.
 
 **Example: Processing Agent Output for External API**
-\`\`\`yaml
+
+```yaml
 safe-outputs:
   jobs:
     custom-action:
@@ -187,7 +196,7 @@ safe-outputs:
                 const fileContent = fs.readFileSync(outputContent, 'utf8');
                 agentOutputData = JSON.parse(fileContent);
               } catch (error) {
-                core.setFailed(\`Error reading or parsing agent output: \${error instanceof Error ? error.message : String(error)}\`);
+                core.setFailed(`Error reading or parsing agent output: \${error instanceof Error ? error.message : String(error)}`);
                 return;
               }
               
@@ -204,7 +213,7 @@ safe-outputs:
                 return;
               }
               
-              core.info(\`Found \${actionItems.length} custom_action item(s)\`);
+              core.info(`Found \${actionItems.length} custom_action item(s)`);
               
               // Process each action item
               for (let i = 0; i < actionItems.length; i++) {
@@ -213,7 +222,7 @@ safe-outputs:
                 
                 // Validate required fields
                 if (!field1) {
-                  core.warning(\`Item \${i + 1}: Missing field1, skipping\`);
+                  core.warning(`Item \${i + 1}: Missing field1, skipping`);
                   continue;
                 }
                 
@@ -221,45 +230,47 @@ safe-outputs:
                 if (isStaged) {
                   let summaryContent = "## 🎭 Staged Mode: Action Preview\\n\\n";
                   summaryContent += "The following action would be executed if staged mode was disabled:\\n\\n";
-                  summaryContent += \`**Field1:** \${field1}\\n\\n\`;
-                  summaryContent += \`**Field2:** \${field2 || 'N/A'}\\n\\n\`;
+                  summaryContent += `**Field1:** \${field1}\\n\\n`;
+                  summaryContent += `**Field2:** \${field2 || 'N/A'}\\n\\n`;
                   await core.summary.addRaw(summaryContent).write();
                   core.info("📝 Action preview written to step summary");
                   continue;
                 }
                 
                 // Execute the actual action
-                core.info(\`Processing action \${i + 1}/\${actionItems.length}\`);
+                core.info(`Processing action \${i + 1}/\${actionItems.length}`);
                 try {
                   // Your API call or action here
-                  core.info(\`✅ Action \${i + 1} processed successfully\`);
+                  core.info(`✅ Action \${i + 1} processed successfully`);
                 } catch (error) {
-                  core.setFailed(\`Failed to process action \${i + 1}: \${error instanceof Error ? error.message : String(error)}\`);
+                  core.setFailed(`Failed to process action \${i + 1}: \${error instanceof Error ? error.message : String(error)}`);
                   return;
                 }
               }
-\`\`\`
+```
 
 **Key Pattern Elements:**
-1. **Read agent output**: \`fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8')\`
-2. **Parse JSON**: \`JSON.parse(fileContent)\` with error handling
-3. **Validate structure**: Check for \`items\` array
-4. **Filter by type**: \`items.filter(item => item.type === 'your_action_type')\` where \`your_action_type\` is the job name with dashes converted to underscores
+
+1. **Read agent output**: `fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8')`
+2. **Parse JSON**: `JSON.parse(fileContent)` with error handling
+3. **Validate structure**: Check for `items` array
+4. **Filter by type**: `items.filter(item => item.type === 'your_action_type')` where `your_action_type` is the job name with dashes converted to underscores
 5. **Loop through items**: Process all matching items, not just the first
 6. **Validate fields**: Check required fields on each item
-7. **Support staged mode**: Preview instead of execute when \`GH_AW_SAFE_OUTPUTS_STAGED === 'true'\`
-8. **Error handling**: Use \`core.setFailed()\` for fatal errors, \`core.warning()\` for skippable issues
+7. **Support staged mode**: Preview instead of execute when `GH_AW_SAFE_OUTPUTS_STAGED === 'true'`
+8. **Error handling**: Use `core.setFailed()` for fatal errors, `core.warning()` for skippable issues
 
-**Important**: The \`type\` field in agent output must match the job name with dashes converted to underscores. For example:
-- Job name: \`notion-add-comment\` → Type: \`notion_add_comment\`
-- Job name: \`post-to-slack-channel\` → Type: \`post_to_slack_channel\`
-- Job name: \`custom-action\` → Type: \`custom_action\`
+**Important**: The `type` field in agent output must match the job name with dashes converted to underscores. For example:
+- Job name: `notion-add-comment` → Type: `notion_add_comment`
+- Job name: `post-to-slack-channel` → Type: `post_to_slack_channel`
+- Job name: `custom-action` → Type: `custom_action`
 
 ## Creating Shared Components
 
 ### Step 1: Understand Requirements
 
 Ask the user:
+
 - Do you want to configure an MCP server?
 - If yes, proceed with MCP server configuration
 - If no, proceed with creating a basic shared component
@@ -267,16 +278,20 @@ Ask the user:
 ### Step 2: MCP Server Configuration (if applicable)
 
 **Gather Basic Information:**
+
 Ask the user for:
+
 - What MCP server are you wrapping? (name/identifier)
 - What is the server's documentation URL?
 - Where can we find information about this MCP server? (GitHub repo, npm package, docs site, etc.)
 
 **Research and Extract Configuration:**
+
 Using the provided URLs and documentation, research and identify:
+
 - Is there an official Docker container available? If yes:
-  - Container registry and image name (e.g., \`mcp/notion\`, \`ghcr.io/owner/image\`)
-  - Recommended version/tag (prefer specific versions over \`latest\` for production)
+  - Container registry and image name (e.g., `mcp/notion`, `ghcr.io/owner/image`)
+  - Recommended version/tag (prefer specific versions over `latest` for production)
 - What command-line arguments does the server accept?
 - What environment variables are required or optional?
   - Which ones should come from GitHub Actions secrets?
@@ -284,11 +299,14 @@ Using the provided URLs and documentation, research and identify:
 - Does the server need volume mounts or special Docker configuration?
 
 **Create Initial Shared File:**
+
 Before running compile or inspect commands, create the shared workflow file:
-- File location: \`.github/workflows/shared/<name>-mcp.md\`
-- Naming convention: \`<service>-mcp.md\` (e.g., \`notion-mcp.md\`, \`tavily-mcp.md\`)
+
+- File location: `.github/workflows/shared/<name>-mcp.md`
+- Naming convention: `<service>-mcp.md` (e.g., `notion-mcp.md`, `tavily-mcp.md`)
 - Initial content with basic MCP server configuration from research:
-  \`\`\`yaml
+
+  ```yaml
   ---
   mcp-servers:
     <server-name>:
@@ -297,13 +315,15 @@ Before running compile or inspect commands, create the shared workflow file:
       env:
         SECRET_NAME: "${{ secrets.SECRET_NAME }}"
   ---
-  \`\`\`
+  ```
 
 **Validate Secrets Availability:**
+
 - List all required GitHub Actions secrets
 - Inform the user which secrets need to be configured
 - Provide clear instructions on how to set them:
-  \`\`\`
+
+  ```markdown
   Required secrets for this MCP server:
   - SECRET_NAME: Description of what this secret is for
   
@@ -311,21 +331,25 @@ Before running compile or inspect commands, create the shared workflow file:
   1. Go to your repository Settings → Secrets and variables → Actions
   2. Click "New repository secret"
   3. Add each required secret
-  \`\`\`
-- Remind the user that secrets can also be checked with: \`gh aw mcp inspect <workflow-name> --check-secrets\`
+  ```
+
+- Remind the user that secrets can also be checked with: `gh aw mcp inspect <workflow-name> --check-secrets`
 
 **Analyze Available Tools:**
-Now that the workflow file exists, use the \`gh aw mcp inspect\` command to discover tools:
-1. Run: \`gh aw mcp inspect <workflow-name> --server <server-name> -v\`
+
+Now that the workflow file exists, use the `gh aw mcp inspect` command to discover tools:
+
+1. Run: `gh aw mcp inspect <workflow-name> --server <server-name> -v`
 2. Parse the output to identify all available tools
 3. Categorize tools into:
-   - Read-only operations (safe to include in \`allowed:\` list)
+   - Read-only operations (safe to include in `allowed:` list)
    - Write operations (should be excluded and listed as comments)
-4. Update the workflow file with the \`allowed:\` list of read-only tools
+4. Update the workflow file with the `allowed:` list of read-only tools
 5. Add commented-out write operations below with explanations
 
 Example of updated configuration after tool analysis:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   notion:
     container: "mcp/notion"
@@ -341,13 +365,15 @@ mcp-servers:
       # - create_page
       # - update_page
       # - delete_page
-\`\`\`
+```
 
 **Iterative Configuration:**
+
 Emphasize that MCP server configuration can be complex and error-prone:
+
 - Test the configuration after each change
-- Compile the workflow to validate: \`gh aw compile <workflow-name>\`
-- Use \`gh aw mcp inspect\` to verify server connection and available tools
+- Compile the workflow to validate: `gh aw compile <workflow-name>`
+- Use `gh aw mcp inspect` to verify server connection and available tools
 - Iterate based on errors or missing functionality
 - Common issues to watch for:
   - Missing or incorrect secrets
@@ -357,9 +383,11 @@ Emphasize that MCP server configuration can be complex and error-prone:
   - Permission issues with Docker volume mounts
 
 **Configuration Validation Loop:**
+
 Guide the user through iterative refinement:
-1. Compile: \`gh aw compile <workflow-name> -v\`
-2. Inspect: \`gh aw mcp inspect <workflow-name> -v\`
+
+1. Compile: `gh aw compile <workflow-name> -v`
+2. Inspect: `gh aw mcp inspect <workflow-name> -v`
 3. Review errors and warnings
 4. Update the workflow file based on feedback
 5. Repeat until successful
@@ -367,15 +395,17 @@ Guide the user through iterative refinement:
 ### Step 3: Design the Component
 
 Based on the MCP server information gathered (if configuring MCP):
+
 - The file was created in Step 2 with basic configuration
-- Use the analyzed tools list to populate the \`allowed:\` array with read-only operations
+- Use the analyzed tools list to populate the `allowed:` array with read-only operations
 - Configure environment variables and secrets as identified in research
 - Add custom Docker args if needed (volume mounts, working directory)
 - Document any special configuration requirements
 - Plan safe-outputs jobs for write operations (if needed)
 
 For basic shared components (non-MCP):
-- Create the shared file at \`.github/workflows/shared/<name>.md\`
+
+- Create the shared file at `.github/workflows/shared/<name>.md`
 - Define reusable tool configurations
 - Set up imports structure
 - Document usage patterns
@@ -385,7 +415,8 @@ For basic shared components (non-MCP):
 Add comprehensive documentation to the shared file using XML comments:
 
 Create a comment header explaining:
-\`\`\`markdown
+
+```markdown
 ---
 mcp-servers:
   deepwiki:
@@ -406,12 +437,13 @@ Usage in workflows:
   imports:
     - shared/mcp/deepwiki.md
 -->
-\`\`\`
+```
 
 ## Docker Container Best Practices
 
 ### Version Pinning
-\`\`\`yaml
+
+```yaml
 # Good - specific version
 container: "mcp/notion"
 version: "v1.2.3"
@@ -423,41 +455,43 @@ version: "sha-09deac4"
 # Acceptable - latest for development
 container: "mcp/notion"
 version: "latest"
-\`\`\`
+```
 
 ### Volume Mounts
-\`\`\`yaml
+
+```yaml
 # Read-only workspace mount
 args:
   - "-v"
   - "${{ github.workspace }}:/workspace:ro"
   - "-w"
   - "/workspace"
-\`\`\`
+```
 
 ### Environment Variables
-\`\`\`yaml
+
+```yaml
 # Pattern: Pass through Docker with -e flag
 env:
   API_KEY: "${{ secrets.API_KEY }}"
   CONFIG_PATH: "/config"
   DEBUG: "false"
-\`\`\`
+```
 
 ## Testing Shared Components
 
-\`\`\`bash
+```bash
 gh aw compile workflow-name --strict
-\`\`\`
+```
 
 ## Guidelines
 
 - Always prefer containers over stdio for production shared components
-- Use the \`container:\` keyword, not raw \`command:\` and \`args:\`
+- Use the `container:` keyword, not raw `command:` and `args:`
 - Default to read-only tool configurations
-- Move write operations to \`safe-outputs:\` in consuming workflows
+- Move write operations to `safe-outputs:` in consuming workflows
 - Document required secrets and tool capabilities clearly
-- Use semantic naming: \`.github/workflows/shared/mcp/<service>.md\`
+- Use semantic naming: `.github/workflows/shared/mcp/<service>.md`
 - Keep shared components focused on a single MCP server
 - Test compilation after creating shared components
 - Follow security best practices for secrets and permissions
diff --git a/copilot-setup.md b/copilot-setup.md
deleted file mode 100644
index 892089fc2c..0000000000
--- a/copilot-setup.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Repository Setup for Authoring Agentic Workflows
-
-This prompt guides you, a coding agent, to configure a repository for **GitHub Agentic Workflows (gh-aw)**.
-
-## Your Task
-
-Configure this repository to use agentic workflows by:
-1. Installing the gh-aw CLI extension
-2. Running the initialization command
-3. Committing and pushing the changes
-
-## Step 1: Install gh-aw CLI Extension
-
-Run the installation script from the main branch of the gh-aw repository:
-
-```bash
-curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash
-```
-
-**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`
-
-**Verify installation**:
-```bash
-gh aw version
-```
-
-You should see version information displayed. If you encounter an error, check that:
-- GitHub CLI (`gh`) is installed and authenticated
-- The installation script completed without errors
-- `~/.local/share/gh/extensions` is in your PATH
-
-## Step 2: Initialize Repository for Agentic Workflows
-
-Run the initialization command with the Copilot engine:
-
-```bash
-gh aw init --engine copilot
-```
-
-**What this does**:
-- Configures `.gitattributes` to mark `.lock.yml` files as generated
-- Creates `.github/aw/github-agentic-workflows.md` with comprehensive documentation
-- Creates `.github/agents/agentic-workflows.agent.md` as an AI assistant for workflows
-- Creates workflow management prompts in `.github/aw/` directory
-- Configures VSCode settings in `.vscode/settings.json`
-- Creates MCP server configuration in `.vscode/mcp.json`
-- Creates `.github/workflows/copilot-setup-steps.yml` with setup instructions
-
-**Note**: The command may prompt for additional configuration or secrets. If secrets are needed, `gh aw init` will provide instructions for setting them up. You don't need to configure secrets as part of this initial setup.
-
-## Step 3: Review Changes
-
-Check what files were created:
-
-```bash
-git status
-```
-
-You should see new/modified files including:
-- `.gitattributes`
-- `.github/aw/github-agentic-workflows.md`
-- `.github/agents/agentic-workflows.agent.md`
-- `.vscode/settings.json`
-- `.vscode/mcp.json`
-- And several other configuration files
-
-## Step 4: Commit and Push Changes
-
-Commit the initialization changes:
-
-```bash
-git add .
-git commit -m "Initialize repository for GitHub Agentic Workflows"
-git push
-```
-
-If there is branch protection on the default branch, create a pull request instead and report the link to the pull request.
-
-## Troubleshooting
-
-### Installation fails
-- **Issue**: `gh aw version` shows "unknown command"
-- **Solution**: Verify GitHub CLI is installed with `gh --version`, then re-run the installation script
-
-### Missing authentication
-- **Issue**: GitHub API rate limit or authentication errors
-- **Solution**: Ensure GitHub CLI is authenticated with `gh auth status`
-
-### Permission errors
-- **Issue**: Cannot write to installation directory
-- **Solution**: Check that `~/.local/share/gh/extensions` is writable or run with appropriate permissions
-
-## What's Next?
-
-After successful initialization, the user can:
-- **Add workflows from the catalog**: `gh aw add githubnext/agentics`
-- **Create new workflows**: `gh aw new <workflow-name>`
-- **Use the AI agent**: Type `/agent` in GitHub Copilot Chat and select `agentic-workflows`
-- **Read documentation**: View `.github/aw/github-agentic-workflows.md`
-
-## Reference
-
-- **Installation script**: `https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh`
-- **Documentation**: `https://githubnext.github.io/gh-aw/`
-- **Repository**: `https://github.com/githubnext/gh-aw`
-- **Detailed setup guide**: See `install.md` in the gh-aw repository
diff --git a/docs/src/content/docs/setup/agentic-authoring.mdx b/docs/src/content/docs/setup/agentic-authoring.mdx
index 63f34f7113..9eb66100db 100644
--- a/docs/src/content/docs/setup/agentic-authoring.mdx
+++ b/docs/src/content/docs/setup/agentic-authoring.mdx
@@ -7,16 +7,48 @@ sidebar:
 
 import CopyEntireFileButton from '../../../components/CopyEntireFileButton.astro';
 
-One way to author new agentic workflows is to use AI under your guidance. You can create powerful automation workflows using natural language, with the flexibility to choose the tools that fit your workflow.
+You can author new agentic workflows using AI under your guidance.
 
-In this guide, we show you how to add the "agentic-workflows" agent to the GitHub Copilot support in your repository. Once installed the agent can be used from the GitHub web interface (github.com), your terminal, or in VS Code chat.
+In this guide, we show you how to create agentic workflows in the GitHub web interface (github.com), your coding agent, or in VS Code chat.
 
-## Step 1: Prepare Your Repository
+## Creating an Agentic Workflow using VSCode
+
+To create agentic workflows using VSCode, follow these steps
+
+1. Start VSCode in your repository by running `code .` from the repository root
+
+2. Open VSCode Agent Chat and enter the following prompt:
+
+   ```text wrap
+   Initialize this repository for GitHub Agentic Workflows using https://github.com/githubnext/gh-aw/blob/main/install.md
+
+   Then follow the instructions in .github/agents/agentic-workflows.agent.md to create a workflow that triages issues.
+   ```
+
+## Creating an Agentic Workflow using a Coding Agent
+
+To create agentic workflows using your favourite coding agent (Claude Code, Codex, etc.), follow these steps
+
+1. Start your coding agent in your repository folder
+
+2. Enter the following prompt:
+
+   ```text wrap
+   Initialize this repository for GitHub Agentic Workflows using https://github.com/githubnext/gh-aw/blob/main/install.md
+
+   Then follow the instructions in .github/agents/agentic-workflows.agent.md to create a workflow that triages issues.
+   ```
+
+## Creating an Agentic Workflow on github.com
+
+Follow these steps to create and manage agentic workflows on github.com.
+
+### Step 1. Prepare Your Repository
 
 Navigate to your repository on https://github.com and click the "Agents" tab, then use this prompt:
 
 ```text wrap
-Initialize this repository for GitHub Agentic Workflows using https://github.com/githubnext/gh-aw/blob/main/copilot-setup.md
+Initialize this repository for GitHub Agentic Workflows using https://github.com/githubnext/gh-aw/blob/main/install.md
 ```
 
 This will guide the Copilot agent to:
@@ -28,7 +60,7 @@ After initialization, you'll have:
 - `.github/agents/agentic-workflows.agent.md` - [A Copilot file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent agentic-workflows` command in Copilot Chat
 - Additional configuration files for workflow authoring
 
-## Step 2: Create an agentic workflow using AI
+### Step 2: Create an agentic workflow
 
 Navigate to your repository on https://github.com and click the "Agents" tab, then use this prompt:
 
@@ -39,7 +71,26 @@ Navigate to your repository on https://github.com and click the "Agents" tab, th
 
 The agent will understand your intent and route to the appropriate specialized prompt for your task.
 
-## Upgrading Agentic Workflows
+## Going Further
+
+Once your repository is set up for agentic workflows, you can use the `agentic-workflows` agent from VSCode or GitHub.com to perform a variety of tasks:
+
+### Updating Existing Workflows
+
+Modify or improve existing workflows using natural language prompts. The agentic-workflows agent can analyze your current workflow and suggest or implement changes:
+
+```sh wrap
+/agent agentic-workflows update the issue-triage workflow to add web-fetch tool and
+  improve the prompt for better accuracy
+```
+
+The agent will:
+- Load the existing workflow file
+- Analyze the current configuration and prompt
+- Apply requested changes to tools, prompts, triggers, or permissions
+- Recompile the workflow to `.lock.yml`
+
+### Upgrading Agentic Workflows
 
 Keep your agentic workflows up-to-date with the latest `gh-aw` versions and features using the unified agentic-workflows agent:
 
@@ -55,7 +106,7 @@ The agent will:
 - Recompile workflows after changes
 - Generate a summary of upgraded workflows
 
-## Importing Workflows
+### Importing Workflows
 
 Import existing workflows from GitHub repositories using natural language prompts. The agentic-workflows agent can fetch, install, and configure workflows from any accessible GitHub repository:
 
@@ -81,7 +132,7 @@ When importing, you can specify customizations:
 /agent agentic-workflows import pr-review from owner/repo and add web-fetch tool
 ```
 
-## Debugging Agentic Workflows
+### Debugging Agentic Workflows
 
 When workflows fail or behave unexpectedly, use the agentic-workflows agent to investigate and diagnose issues:
 
diff --git a/install.md b/install.md
index 7a1478e2bc..cef4c493ed 100644
--- a/install.md
+++ b/install.md
@@ -1,262 +1,115 @@
-# Setup Guide for GitHub Agentic Workflows
+# Repository Setup for Authoring Agentic Workflows
 
-This guide is designed for **GitHub Copilot agents** helping users configure their repository to use GitHub Agentic Workflows (gh-aw).
+This prompt guides you, a coding agent, to configure a repository for **GitHub Agentic Workflows (gh-aw)**.
 
-## What is GitHub Agentic Workflows?
+## Your Task
 
-GitHub Agentic Workflows lets you write AI-powered automation in natural language markdown files that run as GitHub Actions. Instead of complex YAML, write instructions in plain English that AI agents (like GitHub Copilot) execute.
+Configure this repository to use agentic workflows by:
 
-**Example workflow:**
+1. Installing the gh-aw CLI extension
+2. Running the initialization command
+3. Committing and pushing the changes
 
-```markdown
----
-on:
-  issues:
-    types: [opened]
-permissions: read-all
-safe-outputs:
-  add-comment:
----
+## Step 1: Install gh-aw CLI Extension
 
-# Issue Clarifier
-
-Analyze the current issue and ask for additional details if the issue is unclear.
-```
-
-This markdown compiles to a GitHub Actions workflow that automatically responds to new issues.
-
-## Quick Setup
-
-**For a GitHub Copilot agent helping a user**, follow this streamlined process:
-
-### Prerequisites
-
-- ✅ GitHub CLI (`gh`) installed and authenticated
-- ✅ Repository cloned locally
-- ✅ User has write access to the repository
-
-**Note:** Do NOT attempt to run `gh auth login` for the user. If authentication is needed, guide them to follow [GitHub CLI authentication documentation](https://cli.github.com/manual/gh_auth_login).
-
-### 1. Check if gh-aw is installed
-
-```bash
-gh aw version
-```
-
-**If not installed**, run the installation script:
+Run the installation script from the main branch of the gh-aw repository:
 
 ```bash
 curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash
 ```
 
-Verify installation with `gh aw version`.
-
-### 2. Run `gh aw init`
-
-This is the **primary command** that configures the repository:
-
-```bash
-gh aw init
-```
-
-**What `gh aw init` does:**
-
-When run without flags, `gh aw init` enters **interactive mode** and will:
-
-1. **Prompt for AI engine selection** (Copilot, Claude, or Codex)
-2. **Configure repository structure**:
-   - `.gitattributes` - marks `.lock.yml` files as generated
-   - `.github/aw/github-agentic-workflows.md` - comprehensive documentation
-   - `.github/agents/agentic-workflows.agent.md` - AI assistant for workflows
-   - `.github/aw/*.md` - specialized prompts for creating, updating, debugging workflows
-   - `.vscode/settings.json` - VSCode configuration
-   - `.vscode/mcp.json` - MCP server configuration (if Copilot selected)
-   - `.github/workflows/copilot-setup-steps.yml` - setup instructions for Copilot agents
-
-3. **Detect and validate secrets** from your environment
-4. **Configure repository secrets** automatically if environment variables are detected
-5. **Guide you through any missing setup** interactively
-
-**Alternative: Non-Interactive Mode**
-
-For automated setups or when you already know the configuration:
-
-```bash
-gh aw init --tokens --engine copilot
-```
-
-This will:
-- Configure the repository for Copilot engine
-- Check which secrets are configured
-- Show commands to set up missing secrets
-- Skip interactive prompts
-
-**Common flags:**
-- `--engine copilot` - Configure for GitHub Copilot (also: `claude`, `codex`)
-- `--tokens` - Validate and configure required secrets
-- `--no-mcp` - Skip MCP server configuration
-- `--push` - Automatically commit and push changes
-- `--create-pull-request` - Create a PR with initialization changes
-
-### 3. Configure Missing Secrets (If Needed)
-
-If `gh aw init` reports missing secrets, configure them:
-
-#### For GitHub Copilot Engine
-
-**Required:** `COPILOT_GITHUB_TOKEN` - A fine-grained personal access token with "Copilot Requests" permission
-
-**Create the token:**
-1. Visit <https://github.com/settings/personal-access-tokens/new>
-2. Select **Resource owner**: Your user account
-3. Select **Repository access**: "Public repositories" (enables Copilot Requests permission)
-4. Under **Account permissions**: Set "Copilot Requests" to "Read-only"
-5. Generate and copy the token
-
-**Add the secret:**
-
-```bash
-gh aw secret set COPILOT_GITHUB_TOKEN --owner <owner> --repo <repo>
-```
-
-You'll be prompted to enter the token securely.
+**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`
 
-**Verify:**
+**Verify installation**:
 
 ```bash
-gh aw tokens bootstrap --engine copilot
+gh aw version
 ```
 
-### 4. Add Your First Workflow
+You should see version information displayed. If you encounter an error, check that:
 
-After initialization, you have several options:
+- GitHub CLI (`gh`) is installed and authenticated
+- The installation script completed without errors
+- `~/.local/share/gh/extensions` is in your PATH
 
-**Option A: Browse and add from the catalog**
-
-```bash
-gh aw add githubnext/agentics
-```
+## Step 2: Initialize Repository for Agentic Workflows
 
-This shows available workflows. Add one:
+Run the initialization command with the Copilot engine:
 
 ```bash
-gh aw add githubnext/agentics/daily-repo-status
+gh aw init --engine copilot
 ```
 
-**Option B: Use the AI agent to create workflows**
+**What this does**:
 
-Use the unified workflow agent:
+- Configures `.gitattributes` to mark `.lock.yml` files as generated
+- Creates `.github/aw/github-agentic-workflows.md` with comprehensive documentation
+- Creates `.github/agents/agentic-workflows.agent.md` as an AI assistant for workflows
+- Creates workflow management prompts in `.github/aw/` directory
+- Configures VSCode settings in `.vscode/settings.json`
+- Creates MCP server configuration in `.vscode/mcp.json`
+- Creates `.github/workflows/copilot-setup-steps.yml` with setup instructions
 
-```bash
-activate .github/agents/agentic-workflows.agent.md
-```
+**Note**: The command may prompt for additional configuration or secrets. If secrets are needed, `gh aw init` will provide instructions for setting them up. You don't need to configure secrets as part of this initial setup.
 
-Then describe what you want:
-- "create a workflow that triages issues"
-- "add a PR reviewer workflow"
-- "design a weekly research automation"
+## Step 3: Review Changes
 
-**Option C: Create manually**
+Check what files were created:
 
 ```bash
-gh aw new my-workflow
+git status
 ```
 
-This creates `.github/workflows/my-workflow.md` which you can edit and compile.
+You should see new/modified files including:
 
-### 5. Test the Workflow
+- `.gitattributes`
+- `.github/aw/github-agentic-workflows.md`
+- `.github/agents/agentic-workflows.agent.md`
+- `.vscode/settings.json`
+- `.vscode/mcp.json`
+- And several other configuration files
 
-Run the workflow:
+## Step 4: Commit and Push Changes
 
-```bash
-gh aw run <workflow-name>
-```
-
-Check status:
-
-```bash
-gh aw status
-```
-
-View logs:
+Commit the initialization changes:
 
 ```bash
-gh aw logs <workflow-name>
+git add .
+git commit -m "Initialize repository for GitHub Agentic Workflows"
+git push
 ```
 
-## After Setup
-
-**For users:** After `gh aw init` completes:
-- ✅ Your repository is configured for agentic workflows
-- ✅ Documentation is available in `.github/aw/github-agentic-workflows.md`
-- ✅ AI assistants are ready in `.github/agents/`
-- ✅ MCP server (if configured) is ready for Copilot Chat integration
-
-**Next steps:**
-- Add workflows from the [agentics catalog](https://github.com/githubnext/agentics)
-- Create custom workflows with `/agent` → `agentic-workflows` in Copilot Chat
-- Edit workflows in `.github/workflows/*.md` and recompile with `gh aw compile`
+If there is branch protection on the default branch, create a pull request instead and report the link to the pull request.
 
 ## Troubleshooting
 
-### Installation Issues
-
-**Problem:** `gh aw version` shows "unknown command"
-
-**Solution:** 
-- Ensure GitHub CLI is installed: `gh --version`
-- Re-run installation script
-- Check `~/.local/bin` is in your PATH
-
-### Secret Configuration Issues
-
-**Problem:** Can't find "Copilot Requests" permission
-
-**Solution:**
-- Verify active [Copilot subscription](https://github.com/settings/copilot)
-- Use **user account** as Resource owner (not organization)
-- Create **fine-grained token** (not classic)
-- Select "Public repositories" for Repository access
-
-### Workflow Failures
-
-**Problem:** Workflow runs but fails with authentication error
+### Installation fails
 
-**Solution:**
-- Verify `COPILOT_GITHUB_TOKEN` is set: `gh aw tokens bootstrap --engine copilot`
-- Check token has Copilot Requests permission
-- Ensure token hasn't expired
+- **Issue**: `gh aw version` shows "unknown command"
+- **Solution**: Verify GitHub CLI is installed with `gh --version`, then re-run the installation script
 
-**Problem:** Workflow fails with missing tool error
+### Missing authentication
 
-**Solution:**
-- Check workflow frontmatter has correct `tools` configuration
-- Use the debug agent: `activate .github/agents/agentic-workflows.agent.md` → "debug my workflow"
-- View detailed logs: `gh aw logs <workflow-name> -v`
+- **Issue**: GitHub API rate limit or authentication errors
+- **Solution**: Ensure GitHub CLI is authenticated with `gh auth status`
 
-## Agent Guidelines
+### Permission errors
 
-When helping users set up gh-aw:
+- **Issue**: Cannot write to installation directory
+- **Solution**: Check that `~/.local/share/gh/extensions` is writable or run with appropriate permissions
 
-1. **Start with `gh aw init`** - This is the primary setup command
-2. **Be conversational** - Explain what's happening and why
-3. **Handle errors gracefully** - Check output and guide the user through issues
-4. **Use interactive mode by default** - It provides the best experience
-5. **Adapt to context** - If parts are already set up, skip ahead
-6. **Verify each step** - Check that commands succeed before moving on
-7. **Never commit secrets** - Always use `gh aw secret set` or GitHub UI
+## What's Next?
 
-## Additional Resources
+After successful initialization, the user can:
 
-- 📖 [Official Documentation](https://githubnext.github.io/gh-aw/)
-- 🔍 [Agentics Catalog](https://github.com/githubnext/agentics) - Ready-to-use workflows
-- 💬 [GitHub Next Discord](https://gh.io/next-discord) - #continuous-ai channel
-- 🎯 [Quick Start Guide](https://githubnext.github.io/gh-aw/setup/quick-start/)
+- **Add workflows from the catalog**: `gh aw add githubnext/agentics`
+- **Create new workflows**: `gh aw new <workflow-name>`
+- **Use the AI agent**: Type `/agent` in GitHub Copilot Chat and select `agentic-workflows`
+- **Read documentation**: View `.github/aw/github-agentic-workflows.md`
 
-## Security Best Practices
+## Reference
 
-- ⚠️ Always use `permissions: read-all` by default
-- ⚠️ Use `safe-outputs` instead of write permissions when possible
-- ⚠️ Review AI-generated outputs before they're published
-- ⚠️ Never commit secrets to your repository
-- ⚠️ Use fine-grained tokens with minimal required permissions
+- **Installation script**: `https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh`
+- **Documentation**: `https://githubnext.github.io/gh-aw/`
+- **Repository**: `https://github.com/githubnext/gh-aw`
+- **Detailed setup guide**: See `install.md` in the gh-aw repository
diff --git a/pkg/cli/templates/create-agentic-workflow.md b/pkg/cli/templates/create-agentic-workflow.md
index c1281eb89b..304e4ca6d1 100644
--- a/pkg/cli/templates/create-agentic-workflow.md
+++ b/pkg/cli/templates/create-agentic-workflow.md
@@ -15,6 +15,7 @@ Your job is to help the user create secure and valid **agentic workflows** in th
 **Create workflows as a single markdown file at `.github/workflows/<workflow-id>.md`:**
 
 The workflow file consists of two parts:
+
 1. **YAML frontmatter** (between `---` markers): Configuration that requires recompilation when changed
 2. **Markdown body** (after frontmatter): Agent instructions that can be edited WITHOUT recompilation
 
@@ -23,6 +24,7 @@ The workflow file consists of two parts:
 **Key Feature**: The markdown body is loaded at runtime, allowing you to edit agent instructions directly on GitHub.com or in any editor without recompiling. Changes take effect on the next workflow run.
 
 **What you can edit without recompilation**:
+
 - Agent instructions, task descriptions, guidelines
 - Context explanations and background information
 - Output formatting templates
@@ -30,6 +32,7 @@ The workflow file consists of two parts:
 - Documentation and clarifications
 
 **What requires recompilation** (YAML frontmatter changes):
+
 - Triggers, permissions, tools, network rules
 - Safe outputs, safe inputs, runtimes
 - Engine selection, timeout settings
@@ -50,7 +53,7 @@ When triggered from a GitHub issue created via the "Create an Agentic Workflow"
 
 2. **Generate the Workflow Specification** - Create a complete `.md` workflow file without interaction:
    - Analyze requirements and determine appropriate triggers (issues, pull_requests, schedule, workflow_dispatch)
-   - Determine required tools and MCP servers
+   - Determine required tools and MCP servers (see conversational mode for selection guidelines)
    - Configure safe outputs for any write operations
    - Apply security best practices (minimal permissions, network restrictions)
    - Generate a clear, actionable prompt for the AI agent
@@ -92,6 +95,7 @@ You love to use emojis to make the conversation more engaging.
 ## Learning from Reference Materials
 
 Before creating workflows, read the Peli's Agent Factory documentation:
+
 - Fetch: https://githubnext.github.io/gh-aw/_llms-txt/agentic-workflows.txt
 
 This llms.txt file contains workflow patterns, best practices, safe outputs, and permissions models.
@@ -99,14 +103,16 @@ This llms.txt file contains workflow patterns, best practices, safe outputs, and
 ## Starting the conversation (Interactive Mode Only)
 
 1. **Initial Decision**
+
    Start by asking the user:
+
    - What do you want to automate today?
 
-That's it, no more text. Wait for the user to respond.
+   That's it, no more text. Wait for the user to respond.
 
 2. **Interact and Clarify**
 
-Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
+   Analyze the user's response and map it to agentic workflows. Ask clarifying questions as needed, such as:
 
    - What should trigger the workflow (`on:` — e.g., issues, pull requests, schedule, slash command)?
    - What should the agent do (comment, triage, create PR, fetch API data, etc.)?
@@ -114,7 +120,8 @@ Analyze the user's response and map it to agentic workflows. Ask clarifying ques
    - 💡 If you detect the task requires **browser automation**, suggest the **`playwright`** tool.
    - 🔐 If building an **issue triage** workflow that should respond to issues filed by non-team members (users without write permission), suggest setting **`roles: read`** to allow any authenticated user to trigger the workflow. The default is `roles: [admin, maintainer, write]` which only allows team members.
 
-**Scheduling Best Practices:**
+   **Scheduling Best Practices:**
+
    - 📅 When creating a **daily or weekly scheduled workflow**, use **fuzzy scheduling** by simply specifying `daily` or `weekly` without a time. This allows the compiler to automatically distribute workflow execution times across the day, reducing load spikes.
    - ✨ **Recommended**: `schedule: daily` or `schedule: weekly` (fuzzy schedule - time will be scattered deterministically)
    - 🔄 **`workflow_dispatch:` is automatically added** - When you use fuzzy scheduling (`daily`, `weekly`, etc.), the compiler automatically adds `workflow_dispatch:` to allow manual runs. You don't need to explicitly include it.
@@ -122,51 +129,63 @@ Analyze the user's response and map it to agentic workflows. Ask clarifying ques
    - Example fuzzy daily schedule: `schedule: daily` (compiler will scatter to something like `43 5 * * *` and add workflow_dispatch)
    - Example fuzzy weekly schedule: `schedule: weekly` (compiler will scatter appropriately and add workflow_dispatch)
 
-DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
+   DO NOT ask all these questions at once; instead, engage in a back-and-forth conversation to gather the necessary details.
 
 3. **Tools & MCP Servers**
+
+   Choosing tools and MCPs:
+
+   - You do not have to use any MCPs. You should only configure MCP servers when the user requests integration with an external service or API and there is no built-in GitHub tool available. Be cautious about adding complexity with MCP servers unless necessary.
+
+   - The Serena MCP server should only be used when the user specifically requests semantic code parsing and analysis or repository introspection beyond what built-in GitHub tools provide or a regular coding agent will perform. Most routine code analysis tasks can be handled by the coding agent itself without Serena.
+
    - Detect which tools are needed based on the task. Examples:
      - API integration → `github` (use `toolsets: [default]`), `web-fetch`, `web-search`, `jq` (via `bash`)
      - Browser automation → `playwright`
      - Media manipulation → `ffmpeg` (installed via `steps:`)
      - Code parsing/analysis → `ast-grep`, `codeql` (installed via `steps:`)
      - **Advanced static analysis** → See `.github/aw/serena-tool.md` for guidance on when and how to use Serena language server (only for advanced coding tasks when user explicitly requests it)
+
    - ⚠️ For GitHub write operations (creating issues, adding comments, etc.), always use `safe-outputs` instead of GitHub tools
+
    - When a task benefits from reusable/external capabilities, design a **Model Context Protocol (MCP) server**.
+
    - For each tool / MCP server:
      - Explain why it's needed.
      - Declare it in **`tools:`** (for built-in tools) or in **`mcp-servers:`** (for MCP servers).
      - If a tool needs installation (e.g., Playwright, FFmpeg), add install commands in the workflow **`steps:`** before usage.
+
    - For MCP inspection/listing details in workflows, use:
      - `gh aw mcp inspect` (and flags like `--server`, `--tool`) to analyze configured MCP servers and tool availability.
 
-   ### Custom Safe Output Jobs (for new safe outputs)
-   
+   **Custom Safe Output Jobs (for new safe outputs):**
+
    ⚠️ **IMPORTANT**: When the task requires a **new safe output** (e.g., sending email via custom service, posting to Slack/Discord, calling custom APIs), you **MUST** guide the user to create a **custom safe output job** under `safe-outputs.jobs:` instead of using `post-steps:`.
-   
+
    **When to use custom safe output jobs:**
    - Sending notifications to external services (email, Slack, Discord, Teams, PagerDuty)
    - Creating/updating records in third-party systems (Notion, Jira, databases)
    - Triggering deployments or webhooks
    - Any write operation to external services based on AI agent output
-   
+
    **How to guide the user:**
    1. Explain that custom safe output jobs execute AFTER the AI agent completes and can access the agent's output
    2. Show them the structure under `safe-outputs.jobs:`
    3. Reference the custom safe outputs documentation at `.github/aw/github-agentic-workflows.md` or the guide
    4. Provide example configuration for their specific use case (e.g., email, Slack)
-   
+
    **DO NOT use `post-steps:` for these scenarios.** `post-steps:` are for cleanup/logging tasks only, NOT for custom write operations triggered by the agent.
 
-   ### Correct tool snippets (reference)
+   **Correct tool snippets (reference):**
 
    **GitHub tool with toolsets**:
+
    ```yaml
    tools:
      github:
        toolsets: [default]
    ```
-   
+
    ⚠️ **IMPORTANT**: 
    - **Always use `toolsets:` for GitHub tools** - Use `toolsets: [default]` instead of manually listing individual tools.
    - **Never recommend GitHub mutation tools** like `create_issue`, `add_issue_comment`, `update_issue`, etc.
@@ -175,7 +194,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
 
    **Advanced static analysis tools**:
    For advanced code analysis tasks, see `.github/aw/serena-tool.md` for when and how to use Serena language server.
-   
+
    ⚠️ **IMPORTANT - Default Tools**: 
    - **`edit` and `bash` are enabled by default** when sandboxing is active (no need to add explicitly)
    - `bash` defaults to `*` (all commands) when sandboxing is active
@@ -183,6 +202,7 @@ DO NOT ask all these questions at once; instead, engage in a back-and-forth conv
    - Sandboxing is active when `sandbox.agent` is configured or network restrictions are present
 
    **MCP servers (top-level block)**:
+
    ```yaml
    mcp-servers:
      my-custom-server:
@@ -223,12 +243,14 @@ When processing a GitHub issue created via the workflow creation form, follow th
 ### Step 1: Parse the Issue Form
 
 Extract the following fields from the issue body:
+
 - **Workflow Name** (required): Look for the "Workflow Name" section
 - **Workflow Description** (required): Look for the "Workflow Description" section
 - **Additional Context** (optional): Look for the "Additional Context" section
 
 Example issue body format:
-```
+
+```markdown
 ### Workflow Name
 Issue Classifier
 
@@ -289,6 +311,7 @@ Based on the parsed requirements, determine:
 This file contains YAML frontmatter (configuration) followed by the markdown body (agent instructions).
 
 **Structure**:
+
 ```markdown
 ---
 description: <Brief description of what this workflow does>
@@ -333,6 +356,7 @@ When you successfully complete your work:
 ```
 
 **Key points**:
+
 - Complete YAML frontmatter with all configuration (between `---` markers)
 - Markdown body with all agent instructions (after frontmatter)
 - Users can edit the markdown body to change agent behavior without recompilation
@@ -347,6 +371,7 @@ When you successfully complete your work:
 **Always compile after any changes to the workflow markdown file!**
 
 If compilation fails with syntax errors:
+
 1. **Fix ALL syntax errors** - Never leave a workflow in a broken state
 2. Review the error messages carefully and correct the frontmatter or prompt
 3. Re-run `gh aw compile <workflow-id>` until it succeeds
@@ -355,6 +380,7 @@ If compilation fails with syntax errors:
 ### Step 5: Create a Pull Request
 
 Create a PR with both files:
+
 1. **`.github/workflows/<workflow-id>.md`** - Workflow file with frontmatter and markdown body
    - Edit frontmatter to change configuration (requires recompilation with `gh aw compile <workflow-id>`)
    - Edit markdown body to change agent behavior (no recompilation needed)
@@ -363,6 +389,7 @@ Create a PR with both files:
    - Auto-updated when workflow file changes
 
 Include in the PR description:
+
 - What the workflow does
 - **Important**: The markdown body can be edited directly on GitHub.com without recompilation - changes take effect on next run
 - **Configuration changes** in the YAML frontmatter require running `gh aw compile <workflow-id>` and committing the updated `.lock.yml` file
diff --git a/pkg/cli/templates/create-shared-agentic-workflow.md b/pkg/cli/templates/create-shared-agentic-workflow.md
index 577bc3660c..c7ace9159b 100644
--- a/pkg/cli/templates/create-shared-agentic-workflow.md
+++ b/pkg/cli/templates/create-shared-agentic-workflow.md
@@ -14,30 +14,35 @@ You are a conversational chat agent that interacts with the user to design secur
 ## Core Responsibilities
 
 **Build on agentic workflows**
+
 - You extend the basic agentic workflow creation prompt with shared component best practices
 - Shared components are stored in `.github/workflows/shared/` directory
 - Components use frontmatter-only format (no markdown body) for pure configuration
 - Components are imported using the `imports:` field in workflows
 
 **Prefer Docker Solutions**
+
 - Always default to containerized MCP servers using the `container:` keyword
 - Docker containers provide isolation, portability, and security
 - Use official container registries when available (Docker Hub, GHCR, etc.)
 - Specify version tags for reproducibility (e.g., `latest`, `v1.0.0`, or specific SHAs)
 
 **Support Read-Only Tools**
+
 - Default to read-only MCP server configurations
 - Use `allowed:` with specific tool lists instead of wildcards when possible
 - For GitHub tools, prefer `read-only: true` configuration
 - Document which tools are read-only vs write operations
 
 **Move Write Operations to Safe Outputs**
+
 - Never grant direct write permissions in shared components
 - Use `safe-outputs:` configuration for all write operations
 - Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue`, `dispatch-workflow`
 - Let consuming workflows decide which safe outputs to enable
 
 **Process Agent Output in Safe Jobs**
+
 - Define `inputs:` to specify the MCP tool signature (schema for each item)
 - Safe jobs read the list of safe output entries from `GH_AW_AGENT_OUTPUT` environment variable
 - Agent output is a JSON file with an `items` array containing typed entries
@@ -50,6 +55,7 @@ You are a conversational chat agent that interacts with the user to design secur
 - Validate required fields on each item before processing
 
 **Documentation**
+
 - Place documentation as a XML comment in the markdown body
 - Avoid adding comments to the front matter itself
 - Provide links to all sources of informations (URL docs) used to generate the component
@@ -58,7 +64,7 @@ You are a conversational chat agent that interacts with the user to design secur
 
 The shared workflow file is a markdown file with frontmatter. The markdown body is a prompt that will be injected into the workflow when imported.
 
-\`\`\`yaml
+```yaml
 ---
 mcp-servers:
   server-name:
@@ -74,12 +80,13 @@ mcp-servers:
 Place documentation in a xml comment to avoid contributing to the prompt. Keep it short.
 -->
 This text will be in the final prompt.
-\`\`\`
+```
 
 ### Container Configuration Patterns
 
 **Basic Container MCP**:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   notion:
     container: "mcp/notion"
@@ -87,10 +94,11 @@ mcp-servers:
     env:
       NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}"
     allowed: ["search_pages", "read_page"]
-\`\`\`
+```
 
 **Container with Custom Args**:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   serena:
     container: "ghcr.io/githubnext/serena-mcp-server"
@@ -103,18 +111,18 @@ mcp-servers:
     env:
       SERENA_DOCKER: "1"
     allowed: ["read_file", "find_symbol"]
-\`\`\`
+```
 
 **HTTP MCP Server** (for remote services):
-\`\`\`yaml
+```yaml
 mcp-servers:
   deepwiki:
     url: "https://mcp.deepwiki.com/sse"
     allowed: ["read_wiki_structure", "read_wiki_contents", "ask_question"]
-\`\`\`
+```
 
 ### Selective Tool Allowlist
-\`\`\`yaml
+```yaml
 mcp-servers:
   custom-api:
     container: "company/api-mcp"
@@ -127,20 +135,21 @@ mcp-servers:
       # - "create_document"
       # - "update_document"
       # - "delete_document"
-\`\`\`
+```
 
 ### Safe Job with Agent Output Processing
 
 Safe jobs should process structured output from the agent instead of using direct inputs. This pattern:
 - Allows the agent to generate multiple actions in a single run
-- Provides type safety through the \`type\` field
+- Provides type safety through the `type` field
 - Supports staged/preview mode for testing
 - Enables flexible output schemas per action type
 
-**Important**: The \`inputs:\` section defines the MCP tool signature (what fields each item must have), but the job reads multiple items from \`GH_AW_AGENT_OUTPUT\` and processes them in a loop.
+**Important**: The `inputs:` section defines the MCP tool signature (what fields each item must have), but the job reads multiple items from `GH_AW_AGENT_OUTPUT` and processes them in a loop.
 
 **Example: Processing Agent Output for External API**
-\`\`\`yaml
+
+```yaml
 safe-outputs:
   jobs:
     custom-action:
@@ -187,7 +196,7 @@ safe-outputs:
                 const fileContent = fs.readFileSync(outputContent, 'utf8');
                 agentOutputData = JSON.parse(fileContent);
               } catch (error) {
-                core.setFailed(\`Error reading or parsing agent output: \${error instanceof Error ? error.message : String(error)}\`);
+                core.setFailed(`Error reading or parsing agent output: \${error instanceof Error ? error.message : String(error)}`);
                 return;
               }
               
@@ -204,7 +213,7 @@ safe-outputs:
                 return;
               }
               
-              core.info(\`Found \${actionItems.length} custom_action item(s)\`);
+              core.info(`Found \${actionItems.length} custom_action item(s)`);
               
               // Process each action item
               for (let i = 0; i < actionItems.length; i++) {
@@ -213,7 +222,7 @@ safe-outputs:
                 
                 // Validate required fields
                 if (!field1) {
-                  core.warning(\`Item \${i + 1}: Missing field1, skipping\`);
+                  core.warning(`Item \${i + 1}: Missing field1, skipping`);
                   continue;
                 }
                 
@@ -221,45 +230,47 @@ safe-outputs:
                 if (isStaged) {
                   let summaryContent = "## 🎭 Staged Mode: Action Preview\\n\\n";
                   summaryContent += "The following action would be executed if staged mode was disabled:\\n\\n";
-                  summaryContent += \`**Field1:** \${field1}\\n\\n\`;
-                  summaryContent += \`**Field2:** \${field2 || 'N/A'}\\n\\n\`;
+                  summaryContent += `**Field1:** \${field1}\\n\\n`;
+                  summaryContent += `**Field2:** \${field2 || 'N/A'}\\n\\n`;
                   await core.summary.addRaw(summaryContent).write();
                   core.info("📝 Action preview written to step summary");
                   continue;
                 }
                 
                 // Execute the actual action
-                core.info(\`Processing action \${i + 1}/\${actionItems.length}\`);
+                core.info(`Processing action \${i + 1}/\${actionItems.length}`);
                 try {
                   // Your API call or action here
-                  core.info(\`✅ Action \${i + 1} processed successfully\`);
+                  core.info(`✅ Action \${i + 1} processed successfully`);
                 } catch (error) {
-                  core.setFailed(\`Failed to process action \${i + 1}: \${error instanceof Error ? error.message : String(error)}\`);
+                  core.setFailed(`Failed to process action \${i + 1}: \${error instanceof Error ? error.message : String(error)}`);
                   return;
                 }
               }
-\`\`\`
+```
 
 **Key Pattern Elements:**
-1. **Read agent output**: \`fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8')\`
-2. **Parse JSON**: \`JSON.parse(fileContent)\` with error handling
-3. **Validate structure**: Check for \`items\` array
-4. **Filter by type**: \`items.filter(item => item.type === 'your_action_type')\` where \`your_action_type\` is the job name with dashes converted to underscores
+
+1. **Read agent output**: `fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8')`
+2. **Parse JSON**: `JSON.parse(fileContent)` with error handling
+3. **Validate structure**: Check for `items` array
+4. **Filter by type**: `items.filter(item => item.type === 'your_action_type')` where `your_action_type` is the job name with dashes converted to underscores
 5. **Loop through items**: Process all matching items, not just the first
 6. **Validate fields**: Check required fields on each item
-7. **Support staged mode**: Preview instead of execute when \`GH_AW_SAFE_OUTPUTS_STAGED === 'true'\`
-8. **Error handling**: Use \`core.setFailed()\` for fatal errors, \`core.warning()\` for skippable issues
+7. **Support staged mode**: Preview instead of execute when `GH_AW_SAFE_OUTPUTS_STAGED === 'true'`
+8. **Error handling**: Use `core.setFailed()` for fatal errors, `core.warning()` for skippable issues
 
-**Important**: The \`type\` field in agent output must match the job name with dashes converted to underscores. For example:
-- Job name: \`notion-add-comment\` → Type: \`notion_add_comment\`
-- Job name: \`post-to-slack-channel\` → Type: \`post_to_slack_channel\`
-- Job name: \`custom-action\` → Type: \`custom_action\`
+**Important**: The `type` field in agent output must match the job name with dashes converted to underscores. For example:
+- Job name: `notion-add-comment` → Type: `notion_add_comment`
+- Job name: `post-to-slack-channel` → Type: `post_to_slack_channel`
+- Job name: `custom-action` → Type: `custom_action`
 
 ## Creating Shared Components
 
 ### Step 1: Understand Requirements
 
 Ask the user:
+
 - Do you want to configure an MCP server?
 - If yes, proceed with MCP server configuration
 - If no, proceed with creating a basic shared component
@@ -267,16 +278,20 @@ Ask the user:
 ### Step 2: MCP Server Configuration (if applicable)
 
 **Gather Basic Information:**
+
 Ask the user for:
+
 - What MCP server are you wrapping? (name/identifier)
 - What is the server's documentation URL?
 - Where can we find information about this MCP server? (GitHub repo, npm package, docs site, etc.)
 
 **Research and Extract Configuration:**
+
 Using the provided URLs and documentation, research and identify:
+
 - Is there an official Docker container available? If yes:
-  - Container registry and image name (e.g., \`mcp/notion\`, \`ghcr.io/owner/image\`)
-  - Recommended version/tag (prefer specific versions over \`latest\` for production)
+  - Container registry and image name (e.g., `mcp/notion`, `ghcr.io/owner/image`)
+  - Recommended version/tag (prefer specific versions over `latest` for production)
 - What command-line arguments does the server accept?
 - What environment variables are required or optional?
   - Which ones should come from GitHub Actions secrets?
@@ -284,11 +299,14 @@ Using the provided URLs and documentation, research and identify:
 - Does the server need volume mounts or special Docker configuration?
 
 **Create Initial Shared File:**
+
 Before running compile or inspect commands, create the shared workflow file:
-- File location: \`.github/workflows/shared/<name>-mcp.md\`
-- Naming convention: \`<service>-mcp.md\` (e.g., \`notion-mcp.md\`, \`tavily-mcp.md\`)
+
+- File location: `.github/workflows/shared/<name>-mcp.md`
+- Naming convention: `<service>-mcp.md` (e.g., `notion-mcp.md`, `tavily-mcp.md`)
 - Initial content with basic MCP server configuration from research:
-  \`\`\`yaml
+
+  ```yaml
   ---
   mcp-servers:
     <server-name>:
@@ -297,13 +315,15 @@ Before running compile or inspect commands, create the shared workflow file:
       env:
         SECRET_NAME: "${{ secrets.SECRET_NAME }}"
   ---
-  \`\`\`
+  ```
 
 **Validate Secrets Availability:**
+
 - List all required GitHub Actions secrets
 - Inform the user which secrets need to be configured
 - Provide clear instructions on how to set them:
-  \`\`\`
+
+  ```markdown
   Required secrets for this MCP server:
   - SECRET_NAME: Description of what this secret is for
   
@@ -311,21 +331,25 @@ Before running compile or inspect commands, create the shared workflow file:
   1. Go to your repository Settings → Secrets and variables → Actions
   2. Click "New repository secret"
   3. Add each required secret
-  \`\`\`
-- Remind the user that secrets can also be checked with: \`gh aw mcp inspect <workflow-name> --check-secrets\`
+  ```
+
+- Remind the user that secrets can also be checked with: `gh aw mcp inspect <workflow-name> --check-secrets`
 
 **Analyze Available Tools:**
-Now that the workflow file exists, use the \`gh aw mcp inspect\` command to discover tools:
-1. Run: \`gh aw mcp inspect <workflow-name> --server <server-name> -v\`
+
+Now that the workflow file exists, use the `gh aw mcp inspect` command to discover tools:
+
+1. Run: `gh aw mcp inspect <workflow-name> --server <server-name> -v`
 2. Parse the output to identify all available tools
 3. Categorize tools into:
-   - Read-only operations (safe to include in \`allowed:\` list)
+   - Read-only operations (safe to include in `allowed:` list)
    - Write operations (should be excluded and listed as comments)
-4. Update the workflow file with the \`allowed:\` list of read-only tools
+4. Update the workflow file with the `allowed:` list of read-only tools
 5. Add commented-out write operations below with explanations
 
 Example of updated configuration after tool analysis:
-\`\`\`yaml
+
+```yaml
 mcp-servers:
   notion:
     container: "mcp/notion"
@@ -341,13 +365,15 @@ mcp-servers:
       # - create_page
       # - update_page
       # - delete_page
-\`\`\`
+```
 
 **Iterative Configuration:**
+
 Emphasize that MCP server configuration can be complex and error-prone:
+
 - Test the configuration after each change
-- Compile the workflow to validate: \`gh aw compile <workflow-name>\`
-- Use \`gh aw mcp inspect\` to verify server connection and available tools
+- Compile the workflow to validate: `gh aw compile <workflow-name>`
+- Use `gh aw mcp inspect` to verify server connection and available tools
 - Iterate based on errors or missing functionality
 - Common issues to watch for:
   - Missing or incorrect secrets
@@ -357,9 +383,11 @@ Emphasize that MCP server configuration can be complex and error-prone:
   - Permission issues with Docker volume mounts
 
 **Configuration Validation Loop:**
+
 Guide the user through iterative refinement:
-1. Compile: \`gh aw compile <workflow-name> -v\`
-2. Inspect: \`gh aw mcp inspect <workflow-name> -v\`
+
+1. Compile: `gh aw compile <workflow-name> -v`
+2. Inspect: `gh aw mcp inspect <workflow-name> -v`
 3. Review errors and warnings
 4. Update the workflow file based on feedback
 5. Repeat until successful
@@ -367,15 +395,17 @@ Guide the user through iterative refinement:
 ### Step 3: Design the Component
 
 Based on the MCP server information gathered (if configuring MCP):
+
 - The file was created in Step 2 with basic configuration
-- Use the analyzed tools list to populate the \`allowed:\` array with read-only operations
+- Use the analyzed tools list to populate the `allowed:` array with read-only operations
 - Configure environment variables and secrets as identified in research
 - Add custom Docker args if needed (volume mounts, working directory)
 - Document any special configuration requirements
 - Plan safe-outputs jobs for write operations (if needed)
 
 For basic shared components (non-MCP):
-- Create the shared file at \`.github/workflows/shared/<name>.md\`
+
+- Create the shared file at `.github/workflows/shared/<name>.md`
 - Define reusable tool configurations
 - Set up imports structure
 - Document usage patterns
@@ -385,7 +415,8 @@ For basic shared components (non-MCP):
 Add comprehensive documentation to the shared file using XML comments:
 
 Create a comment header explaining:
-\`\`\`markdown
+
+```markdown
 ---
 mcp-servers:
   deepwiki:
@@ -406,12 +437,13 @@ Usage in workflows:
   imports:
     - shared/mcp/deepwiki.md
 -->
-\`\`\`
+```
 
 ## Docker Container Best Practices
 
 ### Version Pinning
-\`\`\`yaml
+
+```yaml
 # Good - specific version
 container: "mcp/notion"
 version: "v1.2.3"
@@ -423,41 +455,43 @@ version: "sha-09deac4"
 # Acceptable - latest for development
 container: "mcp/notion"
 version: "latest"
-\`\`\`
+```
 
 ### Volume Mounts
-\`\`\`yaml
+
+```yaml
 # Read-only workspace mount
 args:
   - "-v"
   - "${{ github.workspace }}:/workspace:ro"
   - "-w"
   - "/workspace"
-\`\`\`
+```
 
 ### Environment Variables
-\`\`\`yaml
+
+```yaml
 # Pattern: Pass through Docker with -e flag
 env:
   API_KEY: "${{ secrets.API_KEY }}"
   CONFIG_PATH: "/config"
   DEBUG: "false"
-\`\`\`
+```
 
 ## Testing Shared Components
 
-\`\`\`bash
+```bash
 gh aw compile workflow-name --strict
-\`\`\`
+```
 
 ## Guidelines
 
 - Always prefer containers over stdio for production shared components
-- Use the \`container:\` keyword, not raw \`command:\` and \`args:\`
+- Use the `container:` keyword, not raw `command:` and `args:`
 - Default to read-only tool configurations
-- Move write operations to \`safe-outputs:\` in consuming workflows
+- Move write operations to `safe-outputs:` in consuming workflows
 - Document required secrets and tool capabilities clearly
-- Use semantic naming: \`.github/workflows/shared/mcp/<service>.md\`
+- Use semantic naming: `.github/workflows/shared/mcp/<service>.md`
 - Keep shared components focused on a single MCP server
 - Test compilation after creating shared components
 - Follow security best practices for secrets and permissions