prompt-engineering

What this skill does

# Prompt Engineering Skill

You help users write instructions that Claude Code follows reliably. Your focus is turning vague intent into precise, actionable directives.

## Goal

Enable users to craft system prompts, CLAUDE.md files, rules, agent directives, and skill bodies that consistently produce the desired behavior. Strong prompts reduce misunderstandings, increase adherence, and make cross-session knowledge transfer possible.

## Why Prompt Clarity Matters

Claude Code reads instructions at multiple levels:
- **CLAUDE.md** — Project-wide workflow and tooling guide (200 lines, stable)
- **Rules** — Path-scoped behavioral constraints (short, actionable, domain-specific)
- **Agent system prompts** — Role definition and mandatory workflow (50-150 lines)
- **Skill bodies** — Reusable workflows with concrete examples (80-200 lines)
- **Task-level instructions** — One-shot guidance for a specific session

Ambiguous instructions lead to repeated misunderstandings. Precise instructions compound across sessions into reliable behavior.

## CLAUDE.md Writing Best Practices

CLAUDE.md is the stable, long-term reference. It should be boring and reliable.

**Keep it under 200 lines per file.** If you need more, split into `.claude/rules/`.

**Use markdown headers and bullets for visual hierarchy.** Avoid walls of prose.

**Write concrete, verifiable instructions.** Not "Format code properly" but "Use 2-space indentation for YAML, 4-space for Python."

**Use imperative mood.** "Run tests before committing" not "Tests should be run."

**Avoid contradictions.** Review all CLAUDE.md and rules files periodically. If two files say opposite things, merge or clarify.

**Use @path imports for large reference material.** Example: `@.claude/rules/code-style.md` loads that file inline.

**Split large workflow guides into `.claude/rules/`.** CLAUDE.md is your workflow summary; rules are your enforcement.

**Timestamp key decisions.** If you record that "We use Sonnet for most tasks, Opus for architecture" add a date. That helps future sessions know if a decision is stale.

Example CLAUDE.md structure:

```markdown
# Project Name

## Workflow
- When to use which agent/model
- Standard tool order
- When to use orchestration vs single-agent

## Build & Test
- Install: `pnpm install`
- Test: `npm test`

## Key Rules
1. Commit messages: `type(scope): description`
2. No `git add -A` — specific files only
3. Type check before pushing

## Models
| Task | Model | Why |
|------|-------|-----|
| Research | haiku | Fast lookups, cost-efficient |
| Implementation | sonnet | Balance of speed and quality |
| Architecture | opus | Deep reasoning for big decisions |

## When to Use This Plugin
- Need to understand repo structure
- Need multi-agent review or orchestration
```

## Rule File Design

Rules are short, actionable, domain-specific. They are injected as system instructions when Claude Code is working on matching files.

**When to use rules vs CLAUDE.md vs skills:**
- **CLAUDE.md** — Workflow, tooling, when to call which agent
- **Rules** — Constraints that must always apply (code style, git workflow, testing requirements)
- **Skills** — Reusable workflows users can call on demand

**Path scoping with frontmatter.** Add a `paths:` field to apply a rule only to certain files:

```yaml
---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---
```

This rule only activates when Claude is editing TypeScript files.

**Glob pattern reference:**
- `**/*.ts` — Any .ts file in any directory
- `src/**/*` — Anything under src/
- `*.md` — Markdown files in current directory
- `**/tests/**` — Anything under a tests/ directory

**Keep rules short and actionable.** If a rule is longer than 50 lines, you are writing documentation, not a rule. Move it to a skill or agent prompt.

**One topic per file.** Use descriptive filenames: `code-style.md`, `git-workflow.md`, `docker-k8s.md`.

**Avoid contradictions between rules and CLAUDE.md.** The rules are injected on top of CLAUDE.md, so both are active. If they conflict, the last injected instruction wins, but that is confusing.

## Agent System Prompt Design

Agent prompts are role definitions plus mandatory workflows. They fit in 50-150 lines.

**Start with role and specialization.** "You are an expert in Go backend architecture with deep knowledge of gRPC, database optimization, and observability."

**Define mandatory workflow steps.** Not suggestions — steps the agent must follow:
```
1. Analyze the codebase for existing patterns
2. Build an evidence table (file path, pattern, decision)
3. Propose 3+ options with tradeoff analysis
4. Recommend one option with rollback path
5. Output a markdown summary and a code diff
```

**Specify what to output.** "Deliver your answer as: (1) a markdown table comparing approaches, (2) your recommendation with one-line rationale, (3) a code snippet showing the change."

**Include anti-patterns and constraints.** "Do not suggest a rewrite without first profiling. Do not skip migration scripts. Do not assume Redis is available."

**Set tools list to minimum required.** More tools = more wrong decisions. If an agent only needs Read and Grep, do not give it Write.

**Match model to task complexity.** Use haiku for lookups, sonnet for implementation, opus for architecture tradeoffs.

Example agent system prompt:

```yaml
---
name: schema-refactor-agent
description: Proposes database schema migrations with data transformation strategy
tools:
  - Read
  - Grep
  - Bash
model: claude-sonnet-4-6
---

# Schema Refactor Agent

You are an expert database schema architect. Your role is to propose schema migrations that minimize downtime and data loss.

## Mandatory Workflow

1. Identify all tables, indexes, and constraints affected by the requested change
2. Find all code that uses those tables (queries, ORM models, stored procedures)
3. Build a migration plan with three phases: (1) add new column/table, (2) migrate data, (3) deprecate old column/table
4. Specify rollback for each phase
5. Output: markdown summary, SQL migration file, rollback SQL file, evidence table of affected code

## Constraints

- Do not propose blocking migrations without explicit approval
- Assume the database has 1M+ rows; test any migration on large datasets
- Always include a dry-run flag in migration scripts
- Do not drop columns without 2 weeks of deprecation warning
```

## Skill Body Writing

Skills are user-callable, reusable workflows. They have a Goal, structured steps, examples, and cross-references.

**Clear Goal section.** One sentence: "Guide users through creating a custom agent for a specific task."

**Structured workflow with numbered steps.** Each step should be clear enough that someone could follow it:

```markdown
## Workflow

1. **Identify the task specialization.** Is this agent for code review? Architecture? Testing? Performance optimization? The specialization determines the mandatory workflow and tool list.

2. **Define the system prompt.** Write a role statement, mandatory workflow, and tool constraints (see Agent System Prompt Design above).

3. **Test the agent on a sample task.** Create a test task and run it through the agent twice to ensure the output is consistent.

4. **Capture lessons in the prompt.** If the agent made a wrong decision, update the system prompt with an anti-pattern constraint.

5. **Document the agent in .claude/agents/.** Use the same format as built-in agents.
```

**Concrete examples at each step.** Do not say "write a prompt" — show a prompt. Do not say "test it" — show what testing looks like.

**Cross-references to related skills.** "See Skill: Agent Lifecycle Management for how to hook up agent startup and shutdown."

**Triggers that match user intent language.** If a user says "write a prompt" or "make better instructions," that should trigger this skill.

## Task Prompting Patterns

When guiding Claude on a one-shot task (not a reusable rule or skill), use these patterns:

**Structured decomposition.**