Skip to content

Commit 2988cbe

Browse files
farmer-dataclaude
farmer-data
and
claude
authored
docs: map custom_instructions to --append-system-prompt (#1480) (#1484)
* docs: map custom_instructions to --append-system-prompt (#1480) The v1 migration guide mapped the v0 `custom_instructions` input to `claude_args: --system-prompt`, but these have different semantics: `custom_instructions` *appended* to Claude Code's default system prompt, while `--system-prompt` *replaces* it entirely. Users who followed the guide silently lost the whole built-in system prompt (tool-usage guidance, sub-agent conventions, etc.), keeping only their few custom lines. Fixes #1480: - Map `custom_instructions` -> `--append-system-prompt` (matches v0 append semantics) in the deprecated-inputs table, the migration example, and the checklist. - Correct the claude_args options table: `--system-prompt` replaces the entire prompt; add an `--append-system-prompt` row for append behavior. Docs-only; no code changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: fix remaining custom_instructions migration references (#1480) Update usage.md, faq.md, and configuration.md to map custom_instructions to --append-system-prompt, matching the migration-guide fix. The override_prompt row is left unchanged since replacement semantics may be intended there. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent a1c0599 commit 2988cbe

4 files changed

Lines changed: 39 additions & 38 deletions

File tree

‎docs/configuration.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -337,17 +337,17 @@ For a complete list of available settings and their descriptions, see the [Claud
337337

338338
Many individual input parameters have been consolidated into `claude_args` or `settings`. Here's how to migrate:
339339

340-
| Old Input | New Approach |
341-
| --------------------- | -------------------------------------------------------- |
342-
| `allowed_tools` | Use `claude_args: "--allowedTools Tool1,Tool2"` |
343-
| `disallowed_tools` | Use `claude_args: "--disallowedTools Tool1,Tool2"` |
344-
| `max_turns` | Use `claude_args: "--max-turns 10"` |
345-
| `model` | Use `claude_args: "--model claude-4-0-sonnet-20250805"` |
346-
| `claude_env` | Use `settings` with `"env"` object |
347-
| `custom_instructions` | Use `claude_args: "--system-prompt 'Your instructions'"` |
348-
| `mcp_config` | Use `claude_args: "--mcp-config '{...}'"` |
349-
| `direct_prompt` | Use `prompt` input instead |
350-
| `override_prompt` | Use `prompt` with GitHub context variables |
340+
| Old Input | New Approach |
341+
| --------------------- | --------------------------------------------------------------- |
342+
| `allowed_tools` | Use `claude_args: "--allowedTools Tool1,Tool2"` |
343+
| `disallowed_tools` | Use `claude_args: "--disallowedTools Tool1,Tool2"` |
344+
| `max_turns` | Use `claude_args: "--max-turns 10"` |
345+
| `model` | Use `claude_args: "--model claude-4-0-sonnet-20250805"` |
346+
| `claude_env` | Use `settings` with `"env"` object |
347+
| `custom_instructions` | Use `claude_args: "--append-system-prompt 'Your instructions'"` |
348+
| `mcp_config` | Use `claude_args: "--mcp-config '{...}'"` |
349+
| `direct_prompt` | Use `prompt` input instead |
350+
| `override_prompt` | Use `prompt` with GitHub context variables |
351351

352352
## Custom Executables for Specialized Environments
353353

‎docs/faq.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ prompt: "Review this PR for security vulnerabilities"
153153
**These inputs are deprecated in v1.0:**
154154

155155
- **`direct_prompt`** → Use `prompt` instead
156-
- **`custom_instructions`** → Use `claude_args` with `--system-prompt`
156+
- **`custom_instructions`** → Use `claude_args` with `--append-system-prompt` (appends to the default system prompt, matching v0 behavior; `--system-prompt` replaces it entirely)
157157

158158
Migration examples:
159159

@@ -165,7 +165,7 @@ custom_instructions: "Focus on security"
165165
# New (v1.0)
166166
prompt: "Review this PR"
167167
claude_args: |
168-
--system-prompt "Focus on security"
168+
--append-system-prompt "Focus on security"
169169
```
170170
171171
### Why doesn't Claude execute my bash commands?

‎docs/migration-guide.md‎

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,19 @@ This guide helps you migrate from Claude Code Action v0.x to v1.0. The new versi
1414

1515
The following inputs have been deprecated and replaced:
1616

17-
| Deprecated Input | Replacement | Notes |
18-
| --------------------- | ------------------------------------ | --------------------------------------------- |
19-
| `mode` | Auto-detected | Action automatically chooses based on context |
20-
| `direct_prompt` | `prompt` | Direct drop-in replacement |
21-
| `override_prompt` | `prompt` | Use GitHub context variables instead |
22-
| `custom_instructions` | `claude_args: --system-prompt` | Move to CLI arguments |
23-
| `max_turns` | `claude_args: --max-turns` | Use CLI format |
24-
| `model` | `claude_args: --model` | Specify via CLI |
25-
| `allowed_tools` | `claude_args: --allowedTools` | Use CLI format |
26-
| `disallowed_tools` | `claude_args: --disallowedTools` | Use CLI format |
27-
| `claude_env` | `settings` with env object | Use settings JSON |
28-
| `mcp_config` | `claude_args: --mcp-config` | Pass MCP config via CLI arguments |
29-
| `timeout_minutes` | Use GitHub Actions `timeout-minutes` | Configure at job level instead of input level |
17+
| Deprecated Input | Replacement | Notes |
18+
| --------------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
19+
| `mode` | Auto-detected | Action automatically chooses based on context |
20+
| `direct_prompt` | `prompt` | Direct drop-in replacement |
21+
| `override_prompt` | `prompt` | Use GitHub context variables instead |
22+
| `custom_instructions` | `claude_args: --append-system-prompt` | Appends to the default prompt (v0 behavior); `--system-prompt` replaces it entirely |
23+
| `max_turns` | `claude_args: --max-turns` | Use CLI format |
24+
| `model` | `claude_args: --model` | Specify via CLI |
25+
| `allowed_tools` | `claude_args: --allowedTools` | Use CLI format |
26+
| `disallowed_tools` | `claude_args: --disallowedTools` | Use CLI format |
27+
| `claude_env` | `settings` with env object | Use settings JSON |
28+
| `mcp_config` | `claude_args: --mcp-config` | Pass MCP config via CLI arguments |
29+
| `timeout_minutes` | Use GitHub Actions `timeout-minutes` | Configure at job level instead of input level |
3030

3131
## Migration Examples
3232

@@ -52,7 +52,7 @@ The following inputs have been deprecated and replaced:
5252
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
5353
claude_args: |
5454
--max-turns 10
55-
--system-prompt "Follow our coding standards"
55+
--append-system-prompt "Follow our coding standards"
5656
--allowedTools Edit,Read,Write
5757
```
5858
@@ -255,14 +255,15 @@ claude_args: |
255255

256256
### Common claude_args Options
257257

258-
| Option | Description | Example |
259-
| ------------------- | ------------------------ | -------------------------------------- |
260-
| `--max-turns` | Limit conversation turns | `--max-turns 10` |
261-
| `--model` | Specify Claude model | `--model claude-4-0-sonnet-20250805` |
262-
| `--allowedTools` | Enable specific tools | `--allowedTools Edit,Read,Write` |
263-
| `--disallowedTools` | Disable specific tools | `--disallowedTools WebSearch` |
264-
| `--system-prompt` | Add system instructions | `--system-prompt "Focus on security"` |
265-
| `--mcp-config` | Add MCP server config | `--mcp-config '{"mcpServers": {...}}'` |
258+
| Option | Description | Example |
259+
| ------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------ |
260+
| `--max-turns` | Limit conversation turns | `--max-turns 10` |
261+
| `--model` | Specify Claude model | `--model claude-4-0-sonnet-20250805` |
262+
| `--allowedTools` | Enable specific tools | `--allowedTools Edit,Read,Write` |
263+
| `--disallowedTools` | Disable specific tools | `--disallowedTools WebSearch` |
264+
| `--system-prompt` | Replace the entire default system prompt | `--system-prompt "Focus on security"` |
265+
| `--append-system-prompt` | Append to the default system prompt (keeps Claude Code's built-in prompt) | `--append-system-prompt "Follow our coding standards"` |
266+
| `--mcp-config` | Add MCP server config | `--mcp-config '{"mcpServers": {...}}'` |
266267

267268
## Provider-Specific Updates
268269

@@ -330,7 +331,7 @@ You can also pass MCP configuration from a file:
330331
- [ ] Remove `mode` input (auto-detected now)
331332
- [ ] Replace `direct_prompt` with `prompt`
332333
- [ ] Replace `override_prompt` with `prompt` using GitHub context
333-
- [ ] Move `custom_instructions` to `claude_args` with `--system-prompt`
334+
- [ ] Move `custom_instructions` to `claude_args` with `--append-system-prompt`
334335
- [ ] Convert `max_turns` to `claude_args` with `--max-turns`
335336
- [ ] Convert `model` to `claude_args` with `--model`
336337
- [ ] Convert `allowed_tools` to `claude_args` with `--allowedTools`

‎docs/usage.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ These inputs are deprecated and will be removed in a future version:
9999
| `mode` | **DEPRECATED**: Mode is now automatically detected based on workflow context | Remove this input; the action auto-detects the correct mode |
100100
| `direct_prompt` | **DEPRECATED**: Use `prompt` instead | Replace with `prompt` |
101101
| `override_prompt` | **DEPRECATED**: Use `prompt` with template variables or `claude_args` with `--system-prompt` | Use `prompt` for templates or `claude_args` for system prompts |
102-
| `custom_instructions` | **DEPRECATED**: Use `claude_args` with `--system-prompt` or include in `prompt` | Move instructions to `prompt` or use `claude_args` |
102+
| `custom_instructions` | **DEPRECATED**: Use `claude_args` with `--append-system-prompt` or include in `prompt` | Move instructions to `prompt` or use `claude_args` |
103103
| `max_turns` | **DEPRECATED**: Use `claude_args` with `--max-turns` instead | Use `claude_args: "--max-turns 5"` |
104104
| `model` | **DEPRECATED**: Use `claude_args` with `--model` instead | Use `claude_args: "--model claude-4-0-sonnet-20250805"` |
105105
| `fallback_model` | **DEPRECATED**: Use `claude_args` with fallback configuration | Configure fallback in `claude_args` or `settings` |
@@ -139,7 +139,7 @@ For a comprehensive guide on migrating from v0.x to v1.0, including step-by-step
139139
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
140140
claude_args: |
141141
--max-turns 10
142-
--system-prompt "Focus on security"
142+
--append-system-prompt "Focus on security"
143143
```
144144
145145
#### Automation Workflows

0 commit comments

Comments
 (0)