anthropics · aulneau · Aug 5, 2025
diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@ A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs an
 - 🛠️ **Flexible Tool Access**: Access to GitHub APIs and file operations (additional tools can be enabled via configuration)
 - 📋 **Progress Tracking**: Visual progress indicators with checkboxes that dynamically update as Claude completes tasks
 - 🏃 **Runs on Your Infrastructure**: The action executes entirely on your own GitHub runner (Anthropic API calls go to your chosen provider)
+- 🎯 **Custom Prompts**: Create tailored prompts with variable substitution (`$PR_NUMBER`, `$CHANGED_FILES`, etc.) for automated workflows
 
 ## Quickstart
 
@@ -29,7 +30,7 @@ This command will guide you through setting up the GitHub app and required secre
 
 - [Setup Guide](./docs/setup.md) - Manual setup, custom GitHub apps, and security best practices
 - [Usage Guide](./docs/usage.md) - Basic usage, workflow configuration, and input parameters
-- [Custom Automations](./docs/custom-automations.md) - Examples of automated workflows and custom prompts
+- [Custom Automations](./docs/custom-automations.md) - Automated workflows, custom prompts with variable substitution
 - [Configuration](./docs/configuration.md) - MCP servers, permissions, environment variables, and advanced settings
 - [Experimental Features](./docs/experimental.md) - Execution modes and network restrictions
 - [Cloud Providers](./docs/cloud-providers.md) - AWS Bedrock and Google Vertex AI setup

diff --git a/docs/custom-automations.md b/docs/custom-automations.md
@@ -62,7 +62,7 @@ Perfect for automatically reviewing PRs from new team members, external contribu
 
 ## Custom Prompt Templates
 
-Use `override_prompt` for complete control over Claude's behavior with variable substitution:
+Use `override_prompt` for complete control over Claude's behavior with variable substitution. Variables are replaced with formatted data from the GitHub context.
 
 ```yaml
 - uses: anthropics/claude-code-action@beta
@@ -82,10 +82,81 @@ Use `override_prompt` for complete control over Claude's behavior with variable
       Provide severity ratings (Critical/High/Medium/Low) for any issues found.
 ```
 
-The `override_prompt` feature supports these variables:
+### Available Variables
+
+| Variable | Description | Example Output | Availability |
+|----------|-------------|----------------|--------------|
+| `$REPOSITORY` | Full repository name | `owner/repo` | All contexts |
+| `$PR_NUMBER` | Pull request number | `123` | PR contexts only |
+| `$ISSUE_NUMBER` | Issue number | `456` | Issue contexts only |
+| `$PR_TITLE` | Pull request title | `feat: add new feature` | PR contexts only |
+| `$ISSUE_TITLE` | Issue title | `Bug: Login not working` | Issue contexts only |
+| `$PR_BODY` | Formatted PR description with images replaced | Multi-line markdown content | PR contexts only |
+| `$ISSUE_BODY` | Formatted issue description with images replaced | Multi-line markdown content | Issue contexts only |
+| `$PR_COMMENTS` | Formatted PR comments | `[username at 2024-01-01]: Comment text`<br/><br/>`[user2 at 2024-01-02]: Another comment` | PR contexts only |
+| `$ISSUE_COMMENTS` | Formatted issue comments | Same format as PR_COMMENTS | Issue contexts only |
+| `$REVIEW_COMMENTS` | Formatted PR review comments with inline code locations | `[Review by user at 2024-01-01]: APPROVED`<br/>`Review body text`<br/>`  [Comment on src/file.js:10]: Inline comment` | PR contexts only |
+| `$CHANGED_FILES` | List of changed files with stats and SHAs | `- src/file.js (MODIFIED) +10/-5 SHA: abc123`<br/>`- docs/readme.md (ADDED) +50/-0 SHA: def456` | PR contexts only |
+| `$TRIGGER_COMMENT` | The comment that triggered Claude | `@claude please review this` | Comment events only |
+| `$TRIGGER_USERNAME` | Username who triggered the action | `johndoe` | All contexts |
+| `$BRANCH_NAME` | Current branch name (claudeBranch or baseBranch) | `feature-123` or `main` | All contexts |
+| `$BASE_BRANCH` | Base branch for PRs/issues | `main` | All contexts |
+| `$EVENT_TYPE` | GitHub event type | `pull_request_review_comment`, `issues`, etc. | All contexts |
+| `$IS_PR` | Whether context is a PR | `true` or `false` | All contexts |
+
+### Important Notes
+
+- **Empty variables**: Variables that don't apply to the current context (e.g., `$PR_NUMBER` in an issue) will be replaced with empty strings
+- **Image handling**: `$PR_BODY`, `$ISSUE_BODY`, and comment variables automatically have image URLs replaced with local file paths
+- **Formatting**: Comments include author and timestamp, changed files include modification stats
+- **Mode availability**: Variable substitution works in all modes (tag, review, agent) when using `override_prompt`
+
+### Variable Output Examples
+
+#### Comments Format
+
+```text
+$PR_COMMENTS outputs:
+[alice at 2024-12-01T10:30:00Z]: This looks great! Just one suggestion below.
+
+[bob at 2024-12-01T11:00:00Z]: I agree with Alice. Also, can we add tests?
+```
+
+#### Changed Files Format
+
+```text
+$CHANGED_FILES outputs:
+- src/components/Button.tsx (MODIFIED) +25/-10 SHA: a1b2c3d4
+- src/components/Button.test.tsx (ADDED) +100/-0 SHA: e5f6g7h8
+- src/old/Legacy.js (DELETED) +0/-150 SHA: deleted
+```
+
+#### Review Comments Format
+
+```text
+$REVIEW_COMMENTS outputs:
+[Review by charlie at 2024-12-01T12:00:00Z]: REQUEST_CHANGES
+Please address the security concern below.
+  [Comment on src/auth.js:45]: This could be vulnerable to SQL injection
+  [Comment on src/auth.js:67]: Consider using prepared statements here
+```
+
+### Mode-Specific Considerations
+
+#### Review Mode
+
+- All PR-related variables are available since review mode only works on pull requests
+- `$TRIGGER_COMMENT` contains the review comment if triggered by a review
+- Variable substitution fully supported with `override_prompt`
+
+#### Agent Mode
+
+- Typically used for automation without PR/issue context
+- PR/issue-specific variables will be empty when no context is available
+- Variable substitution fully supported with `override_prompt`
+
+#### Tag Mode
 
-- `$REPOSITORY`, `$PR_NUMBER`, `$ISSUE_NUMBER`
-- `$PR_TITLE`, `$ISSUE_TITLE`, `$PR_BODY`, `$ISSUE_BODY`
-- `$PR_COMMENTS`, `$ISSUE_COMMENTS`, `$REVIEW_COMMENTS`
-- `$CHANGED_FILES`, `$TRIGGER_COMMENT`, `$TRIGGER_USERNAME`
-- `$BRANCH_NAME`, `$BASE_BRANCH`, `$EVENT_TYPE`, `$IS_PR`
+- Full variable support for both PR and issue contexts
+- Variables adapt based on whether triggered on a PR or issue
+- Variable substitution fully supported with `override_prompt`
diff --git a/docs/usage.md b/docs/usage.md
@@ -52,7 +52,7 @@ jobs:
 | `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                                            | No\*     | -         |
 | `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                                            | No\*     | -         |
 | `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                                 | No       | -         |
-| `override_prompt`              | Complete replacement of Claude's prompt with custom template (supports variable substitution)                                         | No       | -         |
+| `override_prompt`              | Complete replacement of Claude's prompt with custom template. Supports `$VARIABLE` substitution for GitHub context data. See [Custom Automations](./custom-automations.md#custom-prompt-templates) for available variables and examples. | No       | -         |
 | `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                                            | No       | -         |
 | `max_turns`                    | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges)                                                | No       | -         |
 | `timeout_minutes`              | Timeout in minutes for execution                                                                                                      | No       | `30`      |