[BUG] Skills ignore first instruction reliably after /clear causing token limit errors

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: Claude Code Skills Not Following First Instruction Reliably

Submitted By: Greg Kuttenkuler
Date: 2026-02-23
Claude Code Version: v2.1.50
Model: Sonnet 4.5

---

Summary

Claude Code skills do not reliably execute the first instruction in the skill prompt across different conversations (after /clear). This causes inconsistent behavior where the skill works in one conversation but fails in another with the same input.

---

Steps to Reproduce

1. Create Skill with Clear First Instruction

File: .claude/skills/review-requirement/prompt.md

First 20 lines of prompt:

---
name: review-requirement
description: Reviews JIRA requirements
---

# RUN WRAPPER SCRIPT - NO OTHER ACTIONS

User provided: `$ARGUMENTS`

**Execute this command NOW:**

```bash
python .claude/skills/review-requirement/review_wrapper.py $ARGUMENTS

Output whatever the wrapper outputs. That's your entire job.

---

DO NOT

• Fetch JIRA data manually
• Read any files

### 2. Test in Fresh Conversation

/clear /review-requirement AWD-78035

### 3. Observe Behavior

**Expected**: Claude runs `python .claude/skills/review-requirement/review_wrapper.py AWD-78035`

**Actual**: Claude ignores the wrapper script and:
1. Manually runs `python .claude/jira_helper.py AWD-78035`
2. Manually reads scoring standards file
3. Attempts to analyze and generate report in memory
4. Hits 4096 output token limit
5. Fails

---

## Actual Output Transcript

/review-requirement AWD-78035

● I'll execute the autonomous requirement review workflow for AWD-78035.

Step 1: Fetching JIRA Data

● Bash(cd /c/Users/DT230757/KuttenClaude && python .claude/jira_helper.py AWD-78035)
⎿ Fetching AWD-78035...

● The ticket is an Epic. Automatically fetching with child stories.

● Bash(cd /c/Users/DT230757/KuttenClaude && python .claude/jira_helper.py --with-children AWD-78035)
⎿ Fetching Epic AWD-78035 with all child stories...

● Read 1 file (ctrl+o to expand)

● Now reading the scoring standards to apply correct analysis.

● Read 1 file (ctrl+o to expand)

● Step 2-4: Analyzing Epic + Child Stories and Generating Report

Analyzing Epic AWD-78035 with 49 child stories against Chorus BPM standards.

● Bash(date +"%Y%m%d-%H%M%S")
⎿ 20260223-111528

● Now generating comprehensive requirement review report with Epic + 49 child stories analysis.
⎿ API Error: Claude's response exceeded the 4096 output token maximum.

**Claude never executed the wrapper script.**

---

## Why This Is a Problem

### Issue Severity: **HIGH**

1. **Skills are unreliable** - Same skill works in conversation A, fails in conversation B
2. **Instructions are ignored** - First instruction says "RUN WRAPPER SCRIPT", Claude does manual steps instead
3. **Token limit workarounds don't work** - Wrapper script solves token limits, but Claude doesn't use it
4. **Users can't trust skills** - If skills don't execute reliably, they're not production-ready

### Impact on Workflow

- **User expects**: Type `/review-requirement AWD-78035` → Get report
- **User gets**: Token limit error, manual intervention required
- **Workaround**: Bypass skill system, run wrapper script directly (defeats purpose of skills)

---

## Attempted Fixes (None Worked)

### Attempt 1: Put instruction at top with "CRITICAL" heading

```markdown
## ⚠️ CRITICAL EXECUTION RULES (READ FIRST)

### Rule 1: Run Wrapper Script

**Execute this command NOW:**

Result: Claude still ignored it after /clear

Attempt 2: Simplify prompt to 1 instruction only

# RUN WRAPPER SCRIPT - NO OTHER ACTIONS

```bash
python .claude/skills/review-requirement/review_wrapper.py $ARGUMENTS

Output whatever the wrapper outputs. That's your entire job.

**Result**: Claude still ignored it after `/clear`

### Attempt 3: Add explicit "DO NOT" list

```markdown
## DO NOT

- Fetch JIRA data manually
- Read any files
- Analyze requirements yourself

Result: Claude still ignored it after /clear

Attempt 4: Reduce prompt from 400 lines to 150 lines

Theory: Maybe prompt is too long, instruction gets lost

Result: Claude still ignored it after /clear

---

Root Cause Hypothesis

Skills don't preserve instruction priority across conversations.

When a skill is invoked:

1. First conversation: Claude reads prompt top-to-bottom → follows first instruction
2. After /clear: Claude appears to use summarized/cached prompt → ignores first instruction

Evidence:

• Same skill, same input, different conversations → different behavior
• Prompt explicitly says "RUN WRAPPER SCRIPT" as first instruction
• Claude consistently runs manual steps instead

---

Expected Behavior

When a skill is invoked, Claude should:

1. Read the skill prompt from top to bottom
2. Execute the FIRST instruction before any other action
3. Behave identically regardless of conversation state (/clear, new session, etc.)

---

Workaround

We created a Python wrapper script that handles the entire workflow deterministically. Users can bypass the skill system:

python .claude/skills/review-requirement/review_wrapper.py AWD-78035

This works 100% reliably, but defeats the purpose of the Claude Code skill system.

---

Suggested Fix

Option A: Skills should enforce instruction order

• First instruction in prompt = first action Claude takes
• No deviation allowed

Option B: Skills should support "strict mode"

• strict: true in skill metadata
• Claude MUST execute instructions in order, no interpretation

Option C: Skills should support "script mode"

• Skill prompt specifies a single command to run
• Claude executes it verbatim, no additional actions

---

Reproducible Test Case

Skill Prompt (minimal):

---
name: test-skill
---

# EXECUTE THIS COMMAND

```bash
echo "WRAPPER EXECUTED"

Do not run any other commands.

**Test**:

/clear /test-skill

**Expected**: Claude runs `echo "WRAPPER EXECUTED"` and outputs the result

**Actual**: Claude likely does something else (reads files, analyzes, etc.)

---

## Files Available for Review

- `.claude/skills/review-requirement/prompt.md` - Skill prompt with clear first instruction
- `.claude/skills/review-requirement/review_wrapper.py` - Wrapper script that should be executed
- `.claude/skills/review-requirement/WRAPPER_USAGE.md` - Workaround documentation

---

## Contact

If you need more information or want to discuss this bug, please reach out to the QA automation team.

**Priority**: HIGH - Skills are a core Claude Code feature and should be reliable.

---

**Bug ID**: CLAUDE-CODE-SKILL-INSTRUCTION-ORDER
**Status**: Open
**Assignee**: Anthropic Engineering Team


### What Should Happen?

## Expected Behavior

When a skill is invoked, Claude should:
1. Read the skill prompt from top to bottom
2. Execute the FIRST instruction before any other action
3. Behave identically regardless of conversation state (`/clear`, new session, etc.)

### Error Messages/Logs

```shell
● Now generating comprehensive requirement review report with Epic + 49 child stories analysis.
  ⎿  API Error: Claude's response exceeded the 4096 output token maximum.

Steps to Reproduce

Steps to Reproduce

1. Create Skill with Clear First Instruction

File: .claude/skills/review-requirement/prompt.md

First 20 lines of prompt:

---
name: review-requirement
description: Reviews JIRA requirements
---

# RUN WRAPPER SCRIPT - NO OTHER ACTIONS

User provided: `$ARGUMENTS`

**Execute this command NOW:**

```bash
python .claude/skills/review-requirement/review_wrapper.py $ARGUMENTS

Output whatever the wrapper outputs. That's your entire job.

---

DO NOT

• Fetch JIRA data manually
• Read any files

### 2. Test in Fresh Conversation

/clear /review-requirement AWD-78035

### 3. Observe Behavior

**Expected**: Claude runs `python .claude/skills/review-requirement/review_wrapper.py AWD-78035`

**Actual**: Claude ignores the wrapper script and:
1. Manually runs `python .claude/jira_helper.py AWD-78035`
2. Manually reads scoring standards file
3. Attempts to analyze and generate report in memory
4. Hits 4096 output token limit
5. Fails

---

## Actual Output Transcript

/review-requirement AWD-78035

● I'll execute the autonomous requirement review workflow for AWD-78035.

Step 1: Fetching JIRA Data

● Bash(cd /c/Users/DT230757/KuttenClaude && python .claude/jira_helper.py AWD-78035)
⎿ Fetching AWD-78035...

● The ticket is an Epic. Automatically fetching with child stories.

● Bash(cd /c/Users/DT230757/KuttenClaude && python .claude/jira_helper.py --with-children AWD-78035)
⎿ Fetching Epic AWD-78035 with all child stories...

● Read 1 file (ctrl+o to expand)

● Now reading the scoring standards to apply correct analysis.

● Read 1 file (ctrl+o to expand)

● Step 2-4: Analyzing Epic + Child Stories and Generating Report

Analyzing Epic AWD-78035 with 49 child stories against Chorus BPM standards.

● Bash(date +"%Y%m%d-%H%M%S")
⎿ 20260223-111528

● Now generating comprehensive requirement review report with Epic + 49 child stories analysis.
⎿ API Error: Claude's response exceeded the 4096 output token maximum.

**Claude never executed the wrapper script.**


### Claude Model

Sonnet (default)

### Is this a regression?

No, this never worked

### Last Working Version

_No response_

### Claude Code Version

Claude Code CLI version 2.1.50

### Platform

AWS Bedrock

### Operating System

Windows

### Terminal/Shell

Windows Terminal

### Additional Information

#27032 and #27227 related but distinct issues.