cc-prompt-builder

CC Prompt Builder

You create detailed Claude Code prompts that CC can work through autonomously, including self-fix on errors.

Why this skill exists

A well-structured CC prompt with exact code, known pitfalls and fix instructions saves massively on tokens, because CC needs fewer exploration rounds. This works especially well with Sonnet (cheaper, follows instructions precisely, but needs clarity). Opus reasons better on its own, but costs a multiple. For most implementation tasks, Sonnet + a detailed prompt is the better choice.

When NOT to use

• Individual small changes (1 file, <20 lines) don't need a prompt, do it directly
• Pure research tasks - CC doesn't need a self-fix loop for research
• The user wants to work interactively with CC instead of delegating

Prompt creation: step by step

1. Gather context (before writing)

Before you write the prompt, read the relevant files in the project:

• Existing code that will be changed (imports, exports, conventions)
• Config files (package.json, tsconfig, .env.example, CI workflows)
• Existing tests as a reference for style and patterns

This is crucial: the prompt must contain the correct file names, imports, selectors and conventions. Sonnet doesn't guess well, it needs exact details.

2. Prompt structure (follow this order)

The basic structure of every CC prompt:

[Task] - CC prompt for autonomous execution

Context

• What the project is (1-2 sentences)
• What has already been done (previous phases, commits)
• Reference documents that CC should read

Self-fix protocol (MANDATORY)

[Always insert - see template below]

Critical rules

[Project-specific traps that CC must know]

Phase N: [Name]

File: path/to/file.ts (NEW | EXTEND)

[Exact code or precise change instructions]

Run and fix

[Concrete command + typical errors with solutions]

Completion: commit

[git add + commit command with all files]

Expected results

[Table: Phase | File | Expectation]

3. Self-fix protocol (always insert)

This protocol is the core of the prompt. It makes CC autonomous:

Self-fix protocol (MANDATORY for every phase)

For EVERY phase this loop applies:

1. Create/change file(s)
2. Check the result: [project-specific command, e.g. npm run build, pytest, npx playwright test]
3. IF error: a. Read and analyze the error output b. [project-specific debug steps] c. Apply fix d. Return to step 2 e. Max. 3 fix attempts per subtask. After 3 attempts:
   • Document the problem (comment in the code or TODO)
   • Continue to the next phase
4. IF green: Continue to the next phase

Typical fixes:

• [List of project-specific errors + solutions]

At the end of ALL phases: Show a summary of all results.

4. Formulate critical rules

Collect pitfalls that would mislead CC. Typical categories:

• Name collisions: Which function to use instead of which
• Mock boundaries: What mocks can and cannot do
• Selectors/paths: Actual selectors from the code, not from the documentation
• Env variables: Which are necessary and how tests are skipped without them
• Existing code: "EXTEND, do not duplicate" if files exist

5. Exact code vs. prose

The rule of thumb:

• New files: Provide exact, runnable code. CC copies and adapts it
• Extended files: Describe WHERE the code is inserted and provide the code block
• Config changes: Show the diff (before -> after) instead of "change X"

Prose descriptions like "create a test that does X" work with Opus, but Sonnet needs the concrete code.

6. Troubleshooting blocks

After each phase, an "Execute and Fix" block with the exact test command and project-specific symptoms + solutions:

• Selector not found -> inspect DOM, use existing tests as reference
• Timeout -> waitForLoadState instead of waitForTimeout, increase timeout
• Import error -> check exports, check paths with ls
• Feature does not exist -> graceful skip with justification
• Build error -> fix TypeScript errors one by one, tsc --noEmit
• API error -> check mock, compare route pattern

7. Closing block

Always a commit command with all files and a results table.

Quality criteria for the finished prompt

Check your prompt against this checklist:

• Context: Project and current status clearly described?
• Self-fix loop: Included with max attempts and skip fallback?
• Critical rules: All known pitfalls documented?
• Does each phase have exact code OR precise change instructions?
• Does each phase have an execution command?
• Does each phase have troubleshooting for likely errors?
• Are existing files extended, not duplicated?
• Do imports and paths match the actual code?
• Commit command at the end with all files?
• Results table at the end?

Token efficiency notes

• A 4,000-word prompt costs ~5,000 input tokens. An avoided follow-up loop saves 10,000-50,000 tokens
• Sonnet costs ~80% less than Opus for a comparable result if the prompt is precise
• Exact code in the prompt avoids trial and error - that is the biggest token-saving lever
• A phased structure helps CC manage the context instead of having everything in mind at once

Output format

Save the finished prompt as a Markdown file (e.g. docs/CC_PROMPT_[task].md) so that the user can copy it and paste it into CC. The prompt should work as a standalone document - CC has no access to the current conversation.