What's the point of custom_instructions? Why not rely on CLAUDE.md?

[PaulRBerg]

I just installed this and I am unsure what the benefit of this setting is:

# Optional: Add custom instructions for Claude to customize its behavior for your project
# custom_instructions: |
#   Follow our coding standards
#   Ensure all new code has tests
#   Use TypeScript for new files

We already have CLAUDE.md for this (custom context/instructions).

What's the benefit of overloading Claude's API with multiple ways of achieving the same goal?

[ashwin-ant]

We'll be getting rid of custom_instructions in the upcoming v1 release: #428!

[PaulRBerg]

Great news!

On a similar note - does this GitHub Action look up my repo's .claude/settings.json?

Or do I have to manually specify the path to the JSON settings file using the settings input?

[ashwin-ant]

The repo's settings file should be respected, yes!

[naimkatiman]

Good question — they serve different scopes and that's why both exist:

CLAUDE.md = persistent, repo-level instructions

• Lives in your repo, version-controlled
• Applies to every Claude Code session (local CLI, GH Actions, IDE)
• Great for: coding standards, project architecture, always-on rules

custom_instructions = workflow-specific overrides

• Lives in your .github/workflows/*.yml
• Only applies to that specific GitHub Action trigger
• Great for: trigger-specific behavior that differs from normal dev work

When custom_instructions is actually useful

Example: Different behavior per trigger

# PR review workflow
- uses: anthropics/claude-code-action@v1
  with:
    trigger: "review"
    custom_instructions: |
      Focus only on security and performance issues.
      Do not suggest style changes.
      Be concise — max 3 comments per file.

# Issue fix workflow  
- uses: anthropics/claude-code-action@v1
  with:
    trigger: "fix"
    custom_instructions: |
      Always create a new branch.
      Write tests for every fix.
      Run the full test suite before pushing.

You wouldn't put these in CLAUDE.md because they're specific to the GH Action context, not your general dev workflow.

TL;DR

	CLAUDE.md	custom_instructions
Scope	All Claude sessions	One GH Action workflow
Version controlled	Yes (in repo)	Yes (in workflow file)
Use for	Universal project rules	Trigger-specific overrides

Think of CLAUDE.md as your constitution and custom_instructions as executive orders for specific situations. You probably need both if you're running multiple workflow triggers with different expectations.

---

See it in action: before vs after

Before (agent without discipline):

After (agent with continuous-improve installed):

Install: npx continuous-improve-skill — works with Claude Code, Codex, Cursor, and ChatGPT.
Repo: naimkatiman/continuous-improve-skill

[mj-deving]

The answer

Short version: custom_instructions was a v0.x thing, and the Anthropic team already killed it in v1. As @ashwin-ant mentioned, it's on its way out. But the question worth actually answering is: what's the instruction hierarchy in v1, and what belongs where?

Correcting the community reply

@naimkatiman described custom_instructions and CLAUDE.md as having "different scopes" — constitution vs. executive orders. That made sense in v0.x, but it doesn't hold anymore. In v1, custom_instructions is deprecated. You use claude_args: --system-prompt "..." or just put it in prompt instead. The "two tools for two jobs" mental model no longer applies.

One more thing: trigger, as used in that reply's YAML examples, isn't an actual input to this action.

The v1 instruction hierarchy (what actually matters)

Claude Code Action v1 pulls instructions from multiple layers. They stack (concatenate) — nothing overrides anything else. Here's the full picture, broadest to most specific:

Layer	Where it lives	Who it applies to	Loaded when
1. Managed policy	/etc/claude-code/CLAUDE.md (Linux)	All users on the machine	Always, cannot be excluded
2. User-level	~/.claude/CLAUDE.md + ~/.claude/rules/*.md	You, across all projects	Always
3. Project-level	./CLAUDE.md or ./.claude/CLAUDE.md + .claude/rules/*.md	Everyone on the project	Always (repo root and ancestors); on-demand (subdirectories)
4. Local overrides	./CLAUDE.local.md (gitignored)	Just you, this project	Always
5. Workflow-level	claude_args: --system-prompt "..." in your .github/workflows/*.yml	That specific GH Action run	When the workflow fires
6. Prompt	prompt: input in the workflow	That specific GH Action run	When the workflow fires

Layers 1-4 are just standard Claude Code behavior. They work the same whether you're running claude locally, in your IDE, or through the GitHub Action. Layers 5-6 are Action-specific.

Worth noting: in the GH Action context, there's no ~/.claude/CLAUDE.md on the runner — it's a fresh Ubuntu VM every time. So layer 2 is irrelevant unless you explicitly create it in a setup step. Layer 1 only matters if you're on a self-hosted runner with managed policies.

What goes where — practical guidance

In CLAUDE.md (repo root) — universal rules that apply to everyone:

# Build & Test
- Run `pnpm test` before committing
- Use vitest, not jest

# Standards  
- TypeScript strict mode, no `any`
- All public functions need JSDoc

In .claude/rules/ (path-scoped) — rules that only matter for certain files:

# .claude/rules/api.md
---
paths: ["src/api/**/*.ts"]
---
All API endpoints must validate input with zod schemas.

In claude_args: --system-prompt — behavioral overrides for a specific workflow:

# Only for this automation — not a universal project rule
claude_args: |
  --system-prompt "You are reviewing for security issues only. Do not comment on style. Be concise — max 3 comments per file."

In prompt: — the actual task:

prompt: |
  REPO: ${{ github.repository }}
  PR NUMBER: ${{ github.event.pull_request.number }}
  Review this PR for security vulnerabilities.

Settings are also respected

To @PaulRBerg's follow-up: yes, .claude/settings.json in the repo works with the action. Use it for tool permissions, environment variables, MCP config, and other Claude Code settings. You can also pass settings inline or as a file path via the settings: input in your workflow.

TL;DR

custom_instructions is deprecated. Put universal project rules in CLAUDE.md, workflow-specific behavior in --system-prompt via claude_args, and the task itself in prompt. They all stack — nothing overrides anything else.