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