The Specific Situation

Every time you review a PR, you paste the same 15-line prompt into Claude Code: “Check for unused imports, verify error handling, ensure tests cover edge cases, format the review as a checklist.” It works. But you paste it every time, sometimes forgetting a step, and your teammate has a different version of the same prompt. Should you formalize this into a skill, or is the ad-hoc prompt good enough?

Technical Foundation

Raw prompts are instructions typed or pasted directly into the Claude Code chat. They are one-shot: no persistence, no version control, no team sharing, no automatic activation. Claude follows the instructions for the current turn and may forget details in subsequent turns, especially after compaction.

Claude Code skills are SKILL.md files with optional frontmatter. They add: persistence across sessions (just invoke /skill-name), version control through git, team sharing through project commits or plugins, automatic activation via paths field, argument substitution with $ARGUMENTS, tool permission pre-approval with allowed-tools, subagent delegation with context: fork, and dynamic context injection with !command``.

The practical difference: a raw prompt is a sticky note. A skill is a documented procedure in a runbook.

The Working SKILL.md

Formalizing the PR review prompt into a skill:

---
name: pr-review
description: >
  Review changed files in the current PR. Checks unused imports,
  error handling, test coverage, naming conventions, and security
  patterns. Outputs a formatted checklist.
allowed-tools: Bash(git diff *) Read Grep
---

# PR Review Checklist

## Changed Files
!`git diff --name-only HEAD~1 | head -20`

## Review Each Changed File For:

### Code Quality
- [ ] No unused imports (imported but never referenced)
- [ ] No console.log/print statements (use structured logger)
- [ ] Functions under 50 lines
- [ ] No magic numbers (use named constants)
- [ ] Descriptive variable names (not single letters except loop indices)

### Error Handling
- [ ] All async operations have try/catch or .catch()
- [ ] Error messages include context (what operation failed)
- [ ] Errors propagate with stack traces (no swallowed exceptions)
- [ ] User-facing errors are sanitized (no internal details)

### Testing
- [ ] New functions have corresponding test cases
- [ ] Edge cases tested: null input, empty arrays, boundary values
- [ ] Mocked external dependencies (no real API calls in tests)
- [ ] Test names describe the scenario being tested

### Security
- [ ] No hardcoded secrets, tokens, or passwords
- [ ] SQL queries use parameterized inputs
- [ ] User input sanitized before rendering (XSS prevention)
- [ ] API endpoints validate authentication and authorization

## Output Format
For each file, produce:
- File path
- Pass/fail for each checklist item
- Specific issues with line numbers
- Suggested fix for each issue

Where Raw Prompts Win

1. Exploration and experimentation. When you are figuring out what you want Claude to do, typing instructions directly is faster than creating a SKILL.md file, adding frontmatter, and saving to the right directory. Raw prompts are ideal for one-off tasks you will never repeat.

2. Context-dependent instructions. “Review this specific file focusing on the database migration logic because we changed the ORM last week” – this prompt is too specific and temporal to be a reusable skill. It references context that will not apply next week.

3. No setup overhead. Zero files to create, no frontmatter to remember, no directory structure to maintain. For solo developers working on small projects with few repeatable workflows, the overhead of skill creation may not pay off.

Side-by-side comparison of the same task:

Raw prompt (typed every time):
> Check this file for unused imports, missing error
> handling, console.log statements, and functions
> over 50 lines. Format as a checklist.

Skill invocation (one command):
> /pr-review

The skill contains the same instructions but runs identically every time, with dynamic data injected automatically and tool permissions pre-approved.

Where Claude Code Skills Win

1. Consistency. The same checklist runs every time, with every item. Raw prompts drift – you forget the security section on Tuesday, your teammate skips the testing section. Skills are the canonical version.

2. Team sharing. Commit the skill to git. Every team member uses the same review process. No “my prompt vs your prompt” inconsistency. New team members get the workflow on their first git clone.

3. Automatic activation. With paths: ["**/*.ts"], the skill loads automatically when relevant files are open. No remembering to paste the prompt. No forgetting that a review skill exists.

4. Dynamic data. !git diff –name-only HEAD~1`` injects live data into the skill before Claude processes it. Raw prompts require you to manually paste command output.

5. Argument substitution. /pr-review feature/auth-refactor passes the branch name as $ARGUMENTS. Raw prompts require typing the full instruction each time.

6. Tool permissions. allowed-tools: Bash(git diff *) pre-approves git operations without permission prompts. Raw prompts trigger a permission prompt for every tool call.

The Crossover Point

Formalize a prompt into a skill when:

Keep a raw prompt when:

Common Problems and Fixes

Skill is over-engineered for a simple task. Not everything needs a skill. “Format this JSON” does not need a SKILL.md – just type it. Reserve skills for procedures with 5+ steps, multiple checks, or team consistency requirements.

Raw prompt forgotten after session. Claude does not persist chat history across sessions. If you developed a good prompt through iteration, save it as a skill before closing the session. Otherwise, you lose the refined version.

Skill too rigid for evolving workflows. Early-stage projects change rapidly. A skill created in week 1 may be wrong by week 3. Keep skills for stable, proven workflows. Use raw prompts during the exploration phase, then formalize once the workflow stabilizes.

Production Gotchas

Claude Code’s auto-memory feature (MEMORY.md) can partially bridge the gap by saving corrections and preferences across sessions. But auto-memory captures behavioral adjustments (“user prefers X”), not procedural workflows. A complex 20-step review process will not be captured by auto-memory – it needs a skill.

Skills have a maintenance cost. Outdated skills that reference deleted files, renamed commands, or changed workflows cause more confusion than they prevent. Review skills quarterly and archive or update any that reference stale patterns.

Checklist