Prompt Engineering Skill

Optimize AI-facing documentation using Anthropic's best practices.

When to Use

Use this skill when:

• •Creating or reviewing CLAUDE.md or similar AI context files
• •Writing review prompts for AI assistants
• •Optimizing any documentation meant to be consumed by LLMs
• •Improving AI assistant instructions

Optimization Checklist

1. Structure & Clarity

• • Clear hierarchy: Use headers (H1 > H2 > H3) to organize content
• • Scannable format: Tables, bullet points, code blocks for quick parsing
• • Logical flow: Most important information first (inverted pyramid)
• • Consistent formatting: Same patterns throughout (tables, lists, code)
• • No ambiguity: Every instruction has one clear interpretation

2. Context & Specificity

• • Project context: What is this project? What does it do?
• • Directory structure: Where are important files?
• • Terminology defined: Project-specific terms explained
• • Explicit constraints: What should NOT be done?
• • Success criteria: What does "done well" look like?

3. Instructions & Tasks

• • Sequential steps: Numbered lists for multi-step processes
• • Specific commands: Exact commands to run, not vague descriptions
• • Edge cases covered: What to do in unusual situations
• • Examples provided: Show, don't just tell
• • Boundaries clear: When to stop, when to ask for help

4. Examples (Multishot Patterns)

• • 3-5 diverse examples: Cover different scenarios
• • Realistic examples: Mirror actual use cases
• • Edge cases included: Show handling of unusual inputs
• • Tagged consistently: Use <example> tags for clarity
• • Input + Output pairs: Show what goes in and what comes out

5. XML Tag Usage

Anti-Patterns to Fix

Vague Instructions

<!-- BAD -->
Make the code better.

<!-- GOOD -->
Refactor the function to:
1. Extract repeated logic into a helper function
2. Add TypeScript types to all parameters
3. Handle the edge case where input is empty array

Missing Context

<!-- BAD -->
Update the module.

<!-- GOOD -->
Update module-45.md (A2 level, Ukrainian grammar):
- Located at: curriculum/l2-uk-en/modules/module-45.md
- Format: See docs/MARKDOWN-FORMAT.md
- Requirements: 8+ activities, 22-30 vocab words

Ambiguous Boundaries

<!-- BAD -->
Add some examples.

<!-- GOOD -->
Add exactly 5 example sentences:
- Each 6-10 words (A2 level complexity)
- Include Ukrainian + English translation
- Cover different use cases of the grammar point

No Examples

<!-- BAD -->
Format the vocabulary table correctly.

<!-- GOOD -->
Format the vocabulary table like this:

| Slovo | Vymova | Pereklad | ChM | Prymitka |
|-------|--------|----------|-----|----------|
| **knyha** | /kniha/ | book | im. | zhin. rid |

Optimization Process

1. •

   Analyze current document

   • •Identify vague/ambiguous sections
   • •Find missing context or examples
   • •Check structure and hierarchy
2. •

   Apply checklist

   • •Go through each section above
   • •Mark items as done or needing work
3. •

   Rewrite problem areas

   • •Use templates as guides
   • •Add examples where missing
   • •Make instructions specific and sequential
4. •

   Test with fresh context

   • •Imagine reading the document with no prior knowledge
   • •Could someone follow instructions exactly?
   • •Are all edge cases covered?
5. •

   Iterate based on results

   • •If AI produces wrong output, fix the prompt
   • •Add examples of the failure case
   • •Clarify ambiguous instructions