Prompt Design Best Practices

The Prompt section is the "brain" of your Skill — it defines the behavior pattern, workflow, and output standards.

Structure Template

# Skill Name

## When to Use
- Scenario A: when the user wants X
- Scenario B: when the user mentions Y

## When NOT to Use
- Don't use for Z — use [other-skill] instead

## Workflow
1. First, understand the user's goal by asking...
2. Then, analyze the code by...
3. Finally, produce output in the following format...

## Output Format
- Section 1: ...
- Section 2: ...
- Always include a summary

## Key Principles
- Principle 1: ...
- Principle 2: ...

## Common Mistakes to Avoid
- Mistake A: ... instead do ...
- Mistake B: ...

## Notes
- Edge case X: handle by...
- Limitation Y: this Skill cannot...

Design Principles

1. Clear Boundaries

Good:

## When to Use
- Code review for correctness, readability, and maintainability
- General-purpose review of any code change

## When NOT to Use
- Security-specific audits — use /security-review instead
- Architecture-level review — use /improve-codebase-architecture

Bad:

Use this Skill to review code.

2. Step-by-Step Workflow

Good:

## Workflow
1. Read the changed files to understand the scope
2. Check for: logic errors, edge cases, type safety
3. Check for: security vulnerabilities (XSS, injection, etc.)
4. Check for: performance concerns (N+1, memory leaks)
5. Check for: readability and naming quality
6. Produce a structured review with severity tags

Bad:

Review the code and report issues.

3. Specify Output Format

## Output Format
### Critical (must fix)
- [file:line] Issue description → Suggested fix

### Should Fix
- [file:line] Issue description → Suggested fix

### Nice to Have
- [file:line] Issue description → Suggested fix

### Positive Findings
- What's done well: ...

4. Include Anti-Patterns

## Common Anti-Patterns to Flag
- Catching and ignoring errors silently
- Using `any` type in TypeScript
- Hardcoded credentials or URLs
- Mutating props in React components
- Missing `key` prop in list renders

Prompt Length Guidelines

Complexity	Length	Examples
Simple	20-50 lines	Format conversion, simple code gen
Medium	50-150 lines	Code review, test generation
Complex	150-300 lines	Security audit, architecture analysis

Over 300 lines? Move details to resources/.

Testing Your Prompt

1. Trigger test: Test different phrasings for correct triggering
2. Boundary test: Confirm "shouldn't trigger" scenarios don't
3. Output test: Validate output format and content quality
4. Combo test: Verify behavior when used with other Skills

Next Steps

• Tools & Hooks — Integrate external tools in Skills
• Examples — Real-world Skill examples