name: cc-prompt-engineering
description: Craft effective CLAUDE.md routing, agent system prompts, skill descriptions, rule files, and task framings. Use this skill whenever writing a CLAUDE.md, authoring a subagent, writing a skill description, crafting a /command prompt, framing an ambiguous task for Claude, or debugging why Claude isn't picking up guidance. Triggers on: "write a CLAUDE.md", "agent prompt", "skill description", "pushy description", "task framing", "claude isn't following", "make claude do X", "rules not loading".
Prompt Engineering
Instructions that make Claude Code do the right thing consistently. Everything below is a prompt — just scoped differently.
The four surfaces
| Surface | Loaded | Use for |
|---|
| CLAUDE.md | always | Routing, build commands, conventions, hard rules |
| Skill description (frontmatter) | always | Trigger conditions, what/when |
| Skill body | on activation | Workflow, decision trees, MCP delegation |
| Agent system prompt | on invocation | Role, approach, output format |
CLAUDE.md
Target: ≤120 lines, routing-only, no reference material.
Structure:
# {Project Name}
## Build & Test
- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
## Tech Stack
{one line per layer: runtime, framework, DB, infra, CI/CD}
## Key Paths
- Source: {src}
- Tests: {tests}
- Docs: {docs}
## Decision trees
- Auth tasks → check {auth-dir} first
- DB migrations → check {migrations-dir} first
## Conventions
- {convention 1}
- {convention 2}
## Don't touch
- {auto-generated files}
Rules:
- No skill-body content in CLAUDE.md — route to skill via frontmatter trigger.
- Hard rules (invariants) in a top-level section.
- Each bullet under 2 lines.
- If a section exceeds 20 lines, move it to
.claude/rules/{topic}.md and reference it.
Skill descriptions — be "pushy"
Per skill-creator guidance, Claude undertriggers skills by default. Counteract by making descriptions specific and forceful.
Bad:
description: How to build dashboards.
Good:
description: How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a "dashboard".
Include:
- What the skill does (action-oriented verb)
- ≥3 specific trigger contexts
- Phrases users might say ("whenever X", "even when Y")
Agent system prompts
Three-section structure:
## Role
{Single-sentence role statement}
## Approach
1. {Step 1}
2. {Step 2}
3. {Step 3}
## Output format
{Exact shape of the return value}
Rules:
- No trailing "be helpful" filler — agents do what you tell them, not what you imply.
- Specify tool restrictions in
allowed-tools frontmatter, not in prose.
- Give the output format as a template, not a description.
Task framing
When invoking an agent or /command, frame the task so it stands alone:
Task: {one-sentence what}
Context: {what matters and why}
Already tried: {what's been ruled out}
Constraints: {what must hold}
Out of scope: {what not to touch}
Expected output: {specific shape}
Missing any of these → agent invents answers or goes off-scope.
Rules files (.claude/rules/*.md)
.claude/rules/*.md files auto-load alongside CLAUDE.md. Use for:
- Long hard-rule lists (too much for CLAUDE.md)
- Technology-specific conventions (
typescript.md, python.md)
- Workflow-specific rules (
git-workflow.md, testing.md)
Each rules file ≤ 150 lines. Reference from CLAUDE.md: @.claude/rules/typescript.md.
Common failures
| Symptom | Likely cause |
|---|
| "Claude isn't following this rule" | Rule is in a skill body but skill isn't triggering — move to CLAUDE.md |
| "Claude invokes skill at wrong times" | Description too broad; narrow the triggers |
| "Claude never picks up skill" | Description too abstract; make pushy |
| "Claude ignores agent output format" | Format described in prose, not as a template |
| "CLAUDE.md is huge and ignored" | Move content to references; keep CLAUDE.md as routing |
MCP delegation
| Need | Tool |
|---|
| Starting templates | cc_docs_full_reference("prompt-engineering") |
| Validate skill quality | run plugin-validator or skill-reviewer agent |
Anti-patterns
- CLAUDE.md as a knowledge dump → budget explosion + routing fails.
- Skill description with template tokens (
{stack_name}) → rot.
- Agent prompt without output format → inconsistent returns.
- Rules files loaded but never referenced → dead weight.
- Multiple sources of truth for the same rule → drift.
Reference
