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: [email protected] → true,
         invalid → false, [email protected] → 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"
"the API"	"the /api/users endpoint in routes.ts"
"that function"	processPayment() on line 142

Four ways to add context:

Strategy	Example
Scope the task	"write a test for foo.py covering the edge case where user is logged out. avoid mocks."
Point to sources	"look through ExecutionFactory's git history and summarize how its API evolved"
Reference patterns	"look at HotDogWidget.php and follow that pattern for the calendar widget"
Describe symptoms	"users report login fails after session timeout. check src/auth/, especially token refresh"

Respect Project CLAUDE.md:

If the project has a CLAUDE.md, the transformed prompt should:

• Not contradict project conventions
• Reference project-specific patterns when relevant
• Note any project constraints that apply

BEFORE: "add a new API endpoint"
AFTER:  "add a GET /api/products endpoint. check CLAUDE.md for API conventions
         in this project. follow the pattern in routes/users.ts. run the API
         tests after implementing."

BEFORE: "fix the login bug"
AFTER:  "users report login fails after session timeout. check the auth flow
         in src/auth/, especially token refresh. write a failing test that
         reproduces the issue, then fix it"

3. Add Constraints

Tell Claude what NOT to do. Prevents over-engineering and unwanted changes.

Constraint Type	Examples
Dependencies	"no new libraries", "only use existing deps"
Testing	"avoid mocks", "use real database in tests"
Scope	"don't refactor unrelated code", "only touch auth module"
Approach	"address root cause, don't suppress error", "keep backward compat"
Patterns	"follow existing codebase conventions", "match the style in utils.ts"

BEFORE: "add a calendar widget"
AFTER:  "implement a calendar widget with month selection and year pagination.
         follow the pattern in HotDogWidget.php. build from scratch without
         libraries other than the ones already used in the codebase"

4. Structure Complex Tasks in Phases

For larger tasks, separate exploration from implementation.

The 4-Phase Pattern:

Phase 1: EXPLORE
"read src/auth/ and understand how we handle sessions and login.
 also look at how we manage environment variables for secrets."

Phase 2: PLAN
"I want to add Google OAuth. What files need to change?
 What's the session flow? Create a plan."

Phase 3: IMPLEMENT
"implement the OAuth flow from your plan. write tests for the
 callback handler, run the test suite and fix any failures."

Phase 4: COMMIT
"commit with a descriptive message and open a PR"

When to use phases:

• Uncertain about the approach
• Change modifies multiple files
• Unfamiliar with the code being modified

Skip phases when:

• Could describe the diff in one sentence
• Fixing a typo, adding a log line, renaming a variable

BEFORE: "add OAuth"
AFTER:  "read src/auth/ and understand current session handling. create a plan
         for adding OAuth. then implement following the plan. write tests and
         verify they pass"

5. Include Rich Content

Provide supporting materials that Claude can use directly.

Content Type	How to Provide
Files	Use @filename to reference files
Images	Paste screenshots directly
Errors	Paste actual error messages, not descriptions
Logs	Pipe with cat error.log | claude
URLs	Link to relevant documentation

BEFORE: "make the dashboard look better"
AFTER:  "[paste screenshot] implement this design for the dashboard.
         take a screenshot of the result and compare it to the original.
         list any differences and fix them. ensure responsive behavior
         at 768px and 1024px breakpoints"

BEFORE: "the build is failing"
AFTER:  "the build fails with this error: [paste actual error]. fix it
         and verify the build succeeds. address the root cause, don't
         suppress the error"

---

Output Format

When transforming a prompt, output:

**Original:** [their prompt]

**Improved:**

[transformed prompt in code block]

**Added:**
- [what was missing and added]
- [another improvement]
- [etc.]

---

Quick Transformation Examples

Bug Fix

BEFORE: "fix the login bug"

AFTER: "users report login fails after session timeout. check the auth flow
in src/auth/, especially token refresh. write a failing test that reproduces
the issue, then fix it. verify by running the auth test suite."

ADDED: symptom, location, verification (failing test), success criteria

Feature Implementation

BEFORE: "add a search feature"

AFTER: "implement search for the products page. look at how filtering works
in ProductList.tsx for the pattern. search should filter by name and category.
add tests for: empty query returns all, partial match works, no results shows
message. no external search libraries."

ADDED: location, reference pattern, specific behavior, test cases, constraint

Refactoring

BEFORE: "make the code better"

AFTER: "refactor utils.js to use ES2024 features while maintaining the same
behavior. specifically: convert callbacks to async/await, use optional
chaining, add proper TypeScript types. run the existing test suite after
each change to ensure nothing breaks."

ADDED: specific changes, constraint (same behavior), verification after each step

Testing

BEFORE: "add tests for foo.py"

AFTER: "write tests for foo.py covering the edge case where the user is
logged out. avoid mocks. use the existing test patterns in tests/. test
cases: logged_out_user returns 401, expired_session redirects to login,
invalid_token raises AuthError."

ADDED: specific edge case, constraint (no mocks), pattern reference, test cases

Debugging

BEFORE: "the API is slow"

AFTER: "the /api/orders endpoint takes 3+ seconds. profile the database
queries in OrderService.ts. look for N+1 queries or missing indexes.
fix the performance issue and verify response time is under 500ms."

ADDED: specific endpoint, location, what to look for, measurable success criteria

UI Changes

BEFORE: "fix the button styling"

AFTER: "[paste screenshot of design] update the primary button to match this
design. check Button.tsx and the theme in tailwind.config.js. take a
screenshot after changes and compare to the design. list any differences."

ADDED: design reference, file locations, visual verification

Exploration

BEFORE: "how does auth work?"

AFTER: "read src/auth/ and explain how authentication works in this codebase.
cover: how sessions are created, how tokens are refreshed, where secrets
are stored. summarize in a markdown doc."

ADDED: specific files, specific questions to answer, output format

Migration

BEFORE: "upgrade to React 18"

AFTER: "migrate from React 17 to React 18. first, read the migration guide
at [URL]. then identify all components using deprecated APIs. update one
component at a time, running tests after each. don't change unrelated code."

ADDED: phased approach, reference docs, incremental verification, scope constraint

With Verification Report

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."

ADDED: symptom, location, root cause enforcement, verification report

---

Transformation Checklist

Before outputting, verify the improved prompt has:

• Verification — How to know it worked (tests, screenshot, output)
• Location — Specific files, functions, or areas
• Constraints — What NOT to do
• Single task — Not compound (split if needed)
• Phases — If complex, structured as explore → plan → implement
• Root cause — For bugs: "address root cause, don't suppress"
• CLAUDE.md — Respect project conventions if they exist

---

Quick Prompt Quality Check

Rate the prompt against these dimensions:

Dimension	0 (Missing)	1 (Partial)	2 (Complete)
Verification	None	"test it"	Specific test cases + report
Location	"the code"	"auth module"	src/auth/login.ts:42
Constraints	None	Implied	"avoid X, no Y, root cause only"
Scope	Vague	Partial	Single clear task

Quick assessment:

• 0-3: Needs significant work
• 4-5: Needs some improvements
• 6-8: Good, minor tweaks

---

Fallback: If Still Too Vague

If user chose "Transform directly" but the prompt lacks enough context, ask one natural question:

"What would Claude need to know to do this well?"

Don't interrogate — one question is enough. Transform with what you learn.

---

Common Anti-Patterns to Fix

Anti-Pattern	Problem	Fix
"fix the bug"	No symptom, no location	Add what users report + where to look
"add tests"	No scope, no cases	Specify edge cases + test patterns
"make it better"	No criteria for "better"	Define specific improvements
"implement X"	No verification	Add test cases or success criteria
"update the code"	No constraints	Add what to preserve, what to avoid

---

Success Criteria — Prompt Quality Eval

A well-transformed prompt passes these checks:

Principle 1: Verification ✅

Check	Pass	Fail
Has success criteria	"run tests", "screenshot matches"	Nothing
Measurable outcome	"response < 500ms"	"make it faster"
Self-verifiable	Claude can check its own work	Requires human judgment
Root cause enforced	"don't suppress error"	Silent about approach

Principle 2: Specificity ✅

Check	Pass	Fail
File locations	src/auth/login.ts	"the auth code"
Function/class names	processPayment()	"that function"
Line numbers (if relevant)	:42	"somewhere in there"
CLAUDE.md respected	"check project conventions"	Ignores project rules

Principle 3: Constraints ✅

Check	Pass	Fai how to use best-practices CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity How to use best-practices on Cursor AI-first code editor with Composer 1 Prerequisites Before installing skills in Cursor, ensure your development environment meets these requirements: ›Cursor installed and configured on your development machine ›Node.js version 16.0+ with npm package manager (verify with node --version) ›Active project directory or workspace where you want to add best-practices 2 Execute installation command Execute the skills CLI command in your project's root directory to begin installation: $npx skills add https://github.com/skillcreatorai/ai-agent-skills --skill best-practicescopy The skills CLI fetches best-practices from GitHub repository skillcreatorai/ai-agent-skills and configures it for Cursor. 3 Select Cursor when prompted The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor: ◆ Which agents do you want to install to? │ │ ── Universal (.agents/skills) ── always included ──── │ • Amp │ • Antigravity │ • Cline │ • Codex │ ●Cursor(selected) │ • Cursor │ • Windsurf 4 Verify installation Confirm successful installation by checking the skill directory location: .cursor/skills/best-practices Reload or restart Cursor to activate best-practices. Access the skill through slash commands (e.g., /best-practices) or your agent's skill management interface. ⚠ Security & Verification Notice We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use. Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment. Additional Resources ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills? List & Monetize Your Skill Submit your Claude Code skill and start earning GET_STARTED → Use Cases▌ User Story & Requirements Generation Create detailed user stories, acceptance criteria, and feature specs Example Generate user stories for 'password reset feature' with acceptance criteria, edge cases, and test scenarios ✓ Reduce spec writing time by 50%, ensure comprehensive coverage Competitive Analysis Research competitors, compare features, identify gaps Example Analyze 5 competitor products, create feature comparison matrix, suggest differentiation opportunities ✓ Complete competitive research in 2 hours instead of 2 days Roadmap Prioritization Evaluate features using frameworks (RICE, ICE, Kano) and create prioritized backlogs Example Score 20 feature ideas using RICE framework, generate prioritized roadmap with rationale ✓ Make data-driven prioritization decisions faster Stakeholder Communication Draft PRDs, status updates, and stakeholder presentations Example Create executive summary of Q3 roadmap, monthly progress report, feature launch announcement ✓ Save 3-5 hours/week on communication overhead Implementation Guide▌ Prerequisites ›Claude Desktop or compatible AI client ›Access to product documentation and roadmap tools (Jira, Notion, etc.) ›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.) ›Stakeholder contact information and communication channels Time Estimate 30-60 minutes to see productivity improvements Installation Steps 1.Install product management skill 2.Start with user story generation for known feature 3.Progress to competitive analysis: research 2-3 competitors 4.Use for roadmap prioritization: apply RICE/ICE scoring 5.Draft stakeholder communications and refine based on feedback 6.Build template library for recurring PM tasks 7.Share effective prompts with product team Common Pitfalls ⚠Not validating competitive research—verify facts before sharing ⚠Accepting user stories without involving engineering team ⚠Over-relying on frameworks without qualitative judgment ⚠Not customizing outputs to company culture and communication style ⚠Skipping stakeholder validation of generated requirements Best Practices▌ ✓ Do +Validate research and competitive analysis with real data +Collaborate with engineering when generating technical requirements +Customize frameworks and templates to your company context +Use skill for first drafts, refine with stakeholder input +Document successful prompt patterns for PM tasks +Combine AI efficiency with human judgment and intuition ✗ Don't −Don't publish competitive analysis without fact-checking −Don't finalize user stories without engineering review −Don't make prioritization decisions solely on AI scoring −Don't skip customer validation of generated requirements −Don't ignore company-specific context and culture 💡 Pro Tips ★Provide context: company goals, constraints, customer feedback ★Ask for alternatives: 'Show 3 ways to prioritize this roadmap' ★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec' ★Use skill for 70% generation + 30% customization to company needs When to Use This▌ ✓ Use When Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work. ✗ Avoid When Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed. Learning Path▌ 1Basic: user stories, feature specs, status updates 2Intermediate: competitive analysis, prioritization frameworks, PRDs 3Advanced: product strategy, go-to-market planning, OKR setting 4Expert: product vision, market positioning, business model innovation Discussion Product Hunt–style comments (not star reviews) post comment No comments yet — start the thread. general reviews Ratings 4.5★★★★★64 reviews ★★★★★Sofia Agarwal· Dec 24, 2024 best-practices is among the better-maintained entries we tried; worth keeping pinned for repeat workflows. ★★★★★Henry Jackson· Dec 16, 2024 best-practices is among the better-maintained entries we tried; worth keeping pinned for repeat workflows. ★★★★★Ren Li· Dec 8, 2024 Keeps context tight: best-practices is the kind of skill you can hand to a new teammate without a long onboarding doc. ★★★★★Min Farah· Nov 27, 2024 Registry listing for best-practices matched our evaluation — installs cleanly and behaves as described in the markdown. ★★★★★Ren Liu· Nov 15, 2024 best-practices reduced setup friction for our internal harness; good balance of opinion and flexibility. ★★★★★Sakura Diallo· Nov 11, 2024 best-practices fits our agent workflows well — practical, well scoped, and easy to wire into existing repos. ★★★★★Ava Torres· Nov 11, 2024 We added best-practices from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront. ★★★★★Charlotte Brown· Nov 7, 2024 best-practices reduced setup friction for our internal harness; good balance of opinion and flexibility. ★★★★★Charlotte Shah· Oct 26, 2024 Registry listing for best-practices matched our evaluation — installs cleanly and behaves as described in the markdown. ★★★★★Sakura Abebe· Oct 18, 2024 best-practices reduced setup friction for our internal harness; good balance of opinion and flexibility. showing 1-10 of 64 prev1 / 7next bookmarkshare