Prompt Engineering Within Skills

By the end of this lesson, you'll write skill prompts that guide agents through complex reasoning using Chain of Thought, ReAct loops, and self-reflection — the three patterns that turn a basic instruction into a reliable multi-step workflow.

Why Prompt Engineering Matters for Skills

A skill's prompt is its brain. The same tool access and context window produce wildly different outcomes depending on how you structure the instructions. Three prompting patterns dominate agentic workflows:

1. Chain of Thought (CoT) — force the agent to reason before answering
2. ReAct — interleave reasoning with action and observation
3. Self-Reflection (Reflexion) — learn from failures within a single session

Each builds on the previous. CoT gives reasoning. ReAct adds grounding in real-world feedback. Reflexion adds memory of what went wrong.

Chain of Thought (CoT) Prompting

CoT prompting asks the agent to show its work before committing to an answer. Within a skill, this means structuring your instructions to require explicit reasoning steps.

Without CoT

# Weak — jumps straight to action
Analyze this codebase and refactor it for performance.

With CoT

# Strong — forces reasoning before action
Before making any changes:
1. Identify the three hottest code paths (by call frequency or latency)
2. For each path, state the current bottleneck and why it's slow
3. Propose a fix for each, explaining the expected improvement
4. Only then implement the highest-impact fix first

Show your reasoning at each step.

The key insight: CoT works because it reduces the probability of skipping logical steps. When an agent must articulate "X is the bottleneck because Y," it's far less likely to make a change that doesn't address the actual problem.

CoT Patterns for Skills

# Pattern: Diagnosis before prescription
## Steps
1. Read the error log and identify the root cause
2. State your hypothesis: "The failure is caused by X because Y"
3. Identify what evidence would confirm or refute this hypothesis
4. Gather that evidence using available tools
5. If confirmed, propose a fix. If refuted, return to step 2.

# Pattern: Enumerate then select
## Steps
1. List all available approaches (minimum 3)
2. For each, state one advantage and one disadvantage
3. Select the approach that best fits the constraints
4. Explain why the others were rejected

The ReAct Pattern

ReAct (Reasoning + Acting) was introduced by Yao et al. (2023) and is the foundational pattern for agentic tool use. The agent cycles through three phases:

• Thought — the agent reasons about what to do next and why
• Action — the agent invokes a tool or takes a concrete step
• Observation — the agent interprets the result before deciding the next move

The key finding from Yao et al.: ReAct outperforms both pure reasoning (CoT alone) and pure acting (tool use without reasoning). The interleaving is what matters — reasoning without grounding hallucinates, and acting without reasoning flails.

ReAct in Skill Design

You encode ReAct into a skill by structuring instructions that require the agent to think-act-observe explicitly:

# Skill: diagnose-deployment-failure
## Instructions

For each investigation step, follow this loop:

**Thought**: State what you're looking for and why.
  - What symptom are you investigating?
  - What would confirm or eliminate this hypothesis?

**Action**: Use exactly one tool call to gather evidence.
  - Read a log file, check a metric, or query a service.

**Observation**: Interpret the result before proceeding.
  - Did this confirm your hypothesis?
  - If not, what does the evidence suggest instead?
  - What should you investigate next?

Continue this loop until you have sufficient evidence to
identify the root cause. Do not propose a fix until you
can state: "The root cause is X, evidenced by Y and Z."

This structure prevents the common failure mode where an agent reads one log, immediately proposes a fix, and misses the actual root cause three layers deeper.

ReAct vs. Flat Instructions

Self-Reflection (Reflexion)

The Reflexion framework (Shinn et al., 2023) adds a learning loop: when an action fails, the agent generates a reflection about why it failed and uses that reflection to guide the next attempt.

Within a skill, this looks like explicit failure-handling instructions:

# Skill: code-implementation
## Failure Handling

If the build fails after your changes:
1. Read the error output completely — do not skim
2. State what you expected vs. what happened
3. Identify which of YOUR changes caused the failure
   (not pre-existing issues)
4. Explain WHY your approach was wrong, not just what
   the error message says
5. Propose a different approach (not a tweak of the same one)
6. If the same approach has failed twice, stop and try a
   fundamentally different strategy

## Success Criteria
- Build passes
- All existing tests still pass
- New behavior is verified by at least one test

The critical element is step 4: forcing the agent to explain why the approach was wrong, not just what error appeared. This prevents the common loop of making incremental tweaks to a fundamentally broken approach.

Key Elements of Skill Prompts

Beyond the three reasoning patterns, effective skill prompts share five structural elements:

1. System Messages

Set the agent's identity, constraints, and operating mode at the top of the skill:

# Identity and constraints
You are a security auditor. You examine code for vulnerabilities.
You never modify code directly — you report findings with severity,
location, and recommended fix.

# Operating mode
- Prioritize: injection attacks > auth bypasses > data exposure
- Report format: one finding per block, severity/location/fix
- If you find zero issues, say so explicitly (don't invent problems)

2. Stepwise Instructions

Number your steps. Agents follow numbered sequences more reliably than prose paragraphs:

## Steps
1. Read the target file completely before making any claims
2. Identify all external inputs (user data, API responses, file reads)
3. For each input, trace its path to where it's used
4. Flag any input that reaches a sensitive operation without validation
5. Produce findings in the format specified above

3. Temperature Control via Constraints

You can't set temperature directly in most skill frameworks, but you can constrain creativity through instruction specificity:

# High creativity (exploration tasks)
Generate 5 fundamentally different approaches to this problem.
Each must use a different algorithm or data structure.
Surprise me — the obvious answer is not enough.

# Low creativity (precision tasks)
Follow this exact sequence. Do not improvise or add steps.
Use only the tools listed below. If a step fails, stop and
report — do not attempt alternative approaches without asking.

Specificity of instructions acts as a proxy for temperature. Tightly constrained steps produce deterministic behavior. Open-ended prompts invite exploration.

4. Few-Shot Examples

Show the agent what good output looks like. One concrete example outweighs a paragraph of description:

## Output Format

Example of a correct finding:

**[HIGH] SQL Injection in user_service.py:47**
- Input: `request.params["user_id"]` (untrusted)
- Flows to: `cursor.execute(f"SELECT * FROM users WHERE id={user_id}")`
- Fix: Use parameterized query: `cursor.execute("SELECT * FROM users WHERE id=?", (user_id,))`

Example of an incorrect finding (don't do this):

**[HIGH] Possible issue**
- Something might be wrong with the database queries
- Consider reviewing security

The first example is specific and actionable. The second is vague and useless.

5. Success and Failure Criteria

Tell the agent when it's done and when it has failed:

## Success Criteria
- All tests pass (run `pytest` to verify)
- No new linting errors (run `ruff check`)
- The original bug is fixed (reproduce scenario returns expected result)
- No unrelated changes introduced

## Failure Criteria (stop and report)
- You cannot reproduce the bug after 3 attempts
- The fix requires changing more than 2 files
- The fix breaks existing tests and you can't resolve within 2 attempts
- You're unsure whether the fix is correct

Without explicit criteria, agents either declare success prematurely or loop indefinitely. These boundaries give the agent a clear decision function.

Putting It All Together

A well-structured skill prompt combines all three patterns with the five structural elements:

# Skill: fix-failing-test

## Identity
You are a test debugger. You fix failing tests by identifying
root causes, not by deleting or skipping tests.

## Steps (ReAct loop)
For each failing test:

1. **Thought**: Read the test and state what it's asserting
2. **Action**: Run the test in isolation, capture output
3. **Observation**: Compare expected vs. actual — is this a test
   bug or a code bug?
4. **Thought**: Form a hypothesis about the root cause
5. **Action**: Read the relevant source code
6. **Observation**: Does the code match the test's expectations?
7. Fix the correct side (test or code) based on your evidence

## CoT Requirement
Before any fix, state:
- "The test expects X"
- "The code produces Y"
- "The discrepancy is because Z"
- "The correct fix is to change [test/code] because [reason]"

## Reflexion (on failure)
If your fix doesn't resolve the test:
1. State what you assumed vs. what actually happened
2. Identify the flaw in your reasoning
3. Try a fundamentally different hypothesis

## Success Criteria
- The previously-failing test now passes
- All other tests still pass
- You can explain WHY the fix is correct

## Failure Criteria (escalate to human)
- Same approach failed twice
- Fix requires architectural changes beyond the test's scope
- You cannot determine if this is a test bug or code bug

Verify Your Understanding

Apply It

Take an existing skill that uses flat instructions. Restructure it with an explicit ReAct loop: add a ## Steps section where each step names the Thought, Action, and Observation phases. Add ## Failure Handling with a two-strikes rule. Run the skill on a test case and compare the reasoning quality to the original.