Lesson 3 - Crafting High-Fidelity Instructions

Use this structure for every skill you write: ```markdown ## Trigger Activate this skill when [specific scenario]. Do NOT use this skill when [exclusion condition]. ## Workflow 1. [Verb] [specific action with clear details] 2. [Verb] [next action] 3. Check that [validation step] 4. [Verb] [output action] ## Constraints - Never [destructive or out-of-scope action] - Always [required behavior] - If [condition], then [specific response] ## Output Return the result as [specific format]. ### Example Output [Concrete example showing exactly what good output looks like] ```

**Bad: Vague and open to interpretation** ```markdown Review the code and suggest improvements. ``` This produces different results every time. The AI doesn't know what to check, how deep to go, or what format to use. **Good: Specific, structured, and testable** ```markdown ## Workflow 1. Check for unused imports — flag any import not referenced in the file. 2. Check function length — flag any function exceeding 30 lines. 3. Check error handling — flag any try/catch that silently swallows errors. 4. Check naming — flag variables with single-letter names (except loop counters i, j, k). ## Output Return a markdown checklist: - [ ] file:line — issue description — suggested fix ``` This produces consistent results because every step is specific and testable. **Bad: Tries to handle everything** ```markdown Handle all possible code review scenarios including security, performance, accessibility, testing, documentation, and style for all programming languages. ``` **Good: Focused on the 80% case** ```markdown ## Trigger Activate when reviewing TypeScript pull requests. ## Constraints - Focus on code quality only — security and performance are separate skills. - Only review changed files, not the entire codebase. ```

Embed checks directly in your instructions that the AI must satisfy: - **Completion criteria:** `Do not finish until you've verified all items in the checklist pass.` - **Stop conditions:** `If tests fail, stop and return the error logs. Do not attempt fixes.` - **Scope limits:** `Do not modify any files outside the src/ directory.` - **Safety rails:** `Never run destructive commands (DROP, DELETE, rm -rf) during validation.` Quality gates turn your skill from 'nice instructions' into a reliable contract.

You don't need to be technical to write great skills. Here are universal tips: **1. Start with what you know.** If you review documents, manage projects, or write marketing copy — you already have the expertise. Write down your process. **2. Use everyday language.** 'Check if the summary is under 200 words' is better than trying to sound technical. **3. Be direct.** 'Do this. Then do that. Never do this.' Politeness is nice in conversation, but clarity wins in instructions. **4. The 'new colleague' test.** Read your instructions aloud. If a smart new colleague could follow them without questions, they're good enough. **5. Show, don't tell.** One example of good output eliminates pages of description. Include examples. **6. Iterate, don't perfect.** Write version 1, test it, fix where the AI deviated. Three rounds of iteration beat one hour of trying to write perfect instructions.

Keep a lightweight test log as you iterate: | # | Input/Scenario | Expected | Actual | Deviation | Fix Applied | |---|---------------|----------|--------|-----------|-------------| | 1 | Deploy with pending migrations | Flag migrations | Missed migration check | Added explicit step: 'List all unapplied migrations' | | | 2 | Deploy with failing tests | Stop and report | Attempted to fix tests | Added constraint: 'Do NOT attempt fixes — only report' | | | 3 | Re-test after fixes | Both issues caught | Both caught correctly | None — ship it | | This log doubles as documentation for why your instructions evolved.