best-practices

Files (9)

• SKILL.md
• best-practices-referencer.md · agents/
• codebase-context-builder.md · agents/
• task-intent-analyzer.md · agents/
• anti-patterns.md · references/
• before-after-examples.md · references/
• best-practices-guide.md · references/
• common-workflows.md · references/
• prompt-patterns.md · references/

SKILL.md (first lines)

# Best Practices — Prompt Transformer

> Transform prompts by adding what Claude needs to succeed.

## Start Here

Based on user's request:

**User provides a prompt to transform:**
→ Ask using AskUserQuestion:
  - **Question:** "How should I improve this prompt?"
  - **Header:** "Mode"
  - **Options:**
    1. **Transform directly** — "I'll apply best practices and output an improved version"
    2. **Build context first** — "I'll gather codebase context and intent analysis first"

**User asks to learn/understand:**
→ Show the 5 Transformation Principles section

**User asks for examples:**
→ Link to references/before-after-examples.md

**User asks to evaluate a prompt:**
→ Use the Success Criteria eval rubric at the end of this document

---

## If "Transform directly"

Apply the 5 principles below and output the improved prompt immediately.

## If "Build context first"

Launch 3 parallel agents to gather context:

```
Run these agents IN PARALLEL using the Task tool:

- Task task-intent-analyzer("[user's prompt]")
- Task best-practices-referencer("[user's prompt]")
- Task codebase-context-builder("[user's prompt]")
```

### What Each Agent Returns

| Agent | Mission | Returns |
|-------|---------|---------|
| **task-intent-analyzer** | Understand what user is trying to do | Task type, gaps, edge cases, transformation guidance |
| **best-practices-referencer** | Find relevant patterns from references/ | Matching examples, anti-patterns to avoid, transformation rules |
| **codebase-context-builder** | Explore THIS codebase | Specific file paths, similar implementations, conventions |

### After Agents Return

1. **Synthesize findings** — Combine intent + best practices + codebase context
2. **Apply matching patterns** — Use examples from best-practices-referencer as templates
3. **Ground in codebase** — Add specific file paths from codebase-context-builder
4. **Transform the prompt** — Apply the 5 principles with all gathered context
5. **Output** — Show improved prompt with before/after comparison

### Agent Definitions

The agents are defined in `agents/`:
- `agents/task-intent-analyzer.md` — Analyzes intent, gaps, and edge cases
- `agents/best-practices-referencer.md` — Finds relevant examples and patterns from references/
- `agents/codebase-context-builder.md` — Explores codebase for files and conventions

---

## Transformation Workflow

When transforming (after mode selection):

1. **Identify what's missing** — Check against the 5 principles below
2. **Add missing elements** — Verification, context, constraints, phases, rich content
3. **Output the improved prompt** — In a code block, ready to copy-paste
4. **Show what changed** — Brief comparison of before/after

---

## The 5 Transformation Principles

Apply these in order of priority:

### 1. Add Verification (Highest Priority)

**The single highest-leverage improvement.** Claude performs dramatically better when it can verify its own work.

| Missing | Add |
|---------|-----|
| No success criteria | Test cases with expected inputs/outputs |
| UI changes | "take screenshot and compare to design" |
| Bug fixes | "write a failing test, then fix it" |
| Build issues | "verify the build succeeds after fixing" |
| Refactoring | "run the test suite after each change" |
| No root cause enforcement | "address root cause, don't suppress error" |
| No verification report | "summarize what you ran and what passed" |

```
BEFORE: "implement email validation"
AFTER:  "write a validateEmail function. test cases: user@example.com → true,
         invalid → false, user@.com → false. run the tests after implementing"
```

```
BEFORE: "fix the API error"
AFTER:  "the /api/orders endpoint returns 500 for large orders. check
         OrderService.ts for the error. address the root cause, don't suppress
         the error. after fixing, run the test suite and summarize what passed
         and what you verified."
```

### 2. Provide Specific Context

Replace vague references with precise locations and details.

| Vague | Specific |
|-------|----------|
| "the code" | `src/auth/login.ts` |
| "the bug" | "users report X happens when Y" |

From MoizIbnYousaf/ai-agent-skills, MIT.

More from MoizIbnYousaf/ai-agent-skills