Preface¶

When facing complex refactoring, stubborn bugs, or architecture selection decisions, developers often get stuck in the dilemma of “analyze first then act” versus “try first then think”: sticking to one path blindly can lock you into incorrect assumptions; trying out several solutions serially will waste context and time switching back and forth between branches.

best-of-n-solving is exactly the Agent Skill designed for this scenario: first define 2 to 3 mutually non-interfering strategies, then use Cursor’s best-of-n-runner sub-agent to try them in parallel in isolated git worktrees, and finally compare the results and merge the winning solution. It is included in the awesome-cursor-skills maintained by spencerpauly, categorized as a Cursor-Native workflow.

What is this¶

best-of-n-solving is a standard SKILL.md skill instruction that teaches Agents to adopt a “Best-of-N” problem-solving workflow for difficult tasks: each solution exclusively occupies its own branch and working directory without overwriting each other, and after execution, select the optimal solution based on test pass rate, implementation cleanliness, performance and maintainability, then merge it.

Official directory:
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/best-of-n-solving

The YAML description of the Skill is straightforward: use isolated git worktrees to try multiple solutions in parallel, each attempt has an independent branch, then select the best solution; it is suitable for complex refactoring, tricky bugs, or architectural decisions where multiple strategies could work.

Note: This Skill explicitly depends on Cursor’s best-of-n-runner sub-agent type. The SKILL.md itself can be installed into other tools according to the general format of Agent Skills, but the capability of “isolated worktree + parallel runner” is subject to Cursor’s official documentation and the original Skill text.

Core Features and Highlights¶

According to the official SKILL.md, the workflow can be summarized in four steps.

1. Define Strategies First, Then Start Running
   Write down 2 to 3 distinct solutions clearly before launching the task. Official example: when optimizing slow SQL, you can try “composite index + query rewrite”, “materialized view for denormalization”, and “application-layer Redis cache” respectively.

2. Launch best-of-n-runner in Parallel
   Use the Task tool, specify subagent_type: "best-of-n-runner" for each solution, and initiate them all in the same message to let them execute concurrently. Each runner gets an independent branch and worktree, and cannot see each other’s changes.

3. Compare Results by Unified Standards
   After all runs complete, evaluate: which solution passed the tests, which has cleaner implementation, which has better performance, and which is easier to maintain long-term. The Prompt should clearly state the success criteria (for example: “run tests and report whether they pass”, “measure query execution time”).

4. Merge the Winner and Clean Up the Rest
   Check out the winning branch and merge it, or cherry-pick key commits; then clean up other worktree branches. All branches are real git branches, which can be manually reviewed if necessary.

The highlight lies in turning the “multi-strategy trial and error” mental burden from serial execution into an engineering workflow that can be parallelized and reviewed, which is especially suitable for scenarios where “the cost of analysis is high, and trying it out is faster”.

Installation and Activation¶

Method 1: Install via skills CLI (Recommended)¶

The commonly used community installation method is the CLI provided by vercel-labs/skills. To install only this single Skill:

npx skills add spencerpauly/awesome-cursor-skills --skill best-of-n-solving

If your current environment mainly uses Claude Code, you can specify the agent:

npx skills add spencerpauly/awesome-cursor-skills --skill best-of-n-solving --agent claude-code

You can also use a GitHub directory address as the source:

npx skills add https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/best-of-n-solving

Method 2: Manually Place into the Skill Directory¶

The README of awesome-cursor-skills states: Copy the existing SKILL.md into the project’s .cursor/skills/ directory, and the Agent will automatically discover it. The recommended directory structure is as follows:

.cursor/skills/best-of-n-solving/SKILL.md

According to the Cursor official Skills documentation, skills will also be loaded from these locations:

Cursor also reads .claude/skills/, .codex/skills/ and their corresponding user directories for compatibility. After installation, you can manually call it by searching for best-of-n-solving with / in the Agent chat; the Agent may also automatically select it when the description matches.

Typical Usage Examples¶

The following examples are directly from the step instructions of the official Skill, and you can rewrite the Prompt according to your own problem.

1. First List the Strategies (Taking Slow Query as an Example)
- Approach A: Add composite index and rewrite the query
- Approach B: Use materialized view for denormalization
- Approach C: Add application-layer Redis cache

2. Launch Runners in Parallel in the Same Message

Task 1: { subagent_type: "best-of-n-runner", prompt: "Approach A: ..." }
Task 2: { subagent_type: "best-of-n-runner", prompt: "Approach B: ..." }
Task 3: { subagent_type: "best-of-n-runner", prompt: "Approach C: ..." }

It is recommended to clearly write the relevant file paths, problem description, and success criteria (what to test and how to judge passing) in each Prompt.

3. Compare and Merge
After the runners finish, select the solution based on tests, code quality, performance, and maintainability; then:

git checkout <winning-branch>
git merge <winning-branch>
# Or cherry-pick the required commits, then delete other worktrees / branches

Applicable Scenarios and Notes¶

The applicable scenarios listed by the official include:
- Bugs may have multiple root causes and need parallel verification
- Hesitating between patterns like composable vs inheritance during refactoring
- Multiple strategies exist for performance optimization
- Trying different libraries or implementation paths for the same function
- Scenarios where “trying it out first” is more cost-effective than continuing paper analysis

Notes (all from the original Skill text):
- Each runner is completely isolated and cannot see each other’s changes, do not assume that intermediate results can be shared.
- The Prompt needs to be specific: file paths, problems, and success criteria are all indispensable.
- Do not use Best-of-N for simple problems; a single Agent is sufficient, otherwise it is over-engineering.
- The output is real git branches, which can be reviewed manually via git log / git diff before merging.
- The core parallel capability is bound to Cursor’s best-of-n-runner; installing only the SKILL.md in other Agents does not automatically equip the same set of worktree runners.

Summary¶

best-of-n-solving turns “multi-solution trial and error” into a reusable Agent workflow: define strategies → parallel runners → comparison → merge the winner. It is especially useful for complex refactoring, difficult bugs, and architectural branching decisions, and is also a clear case for understanding Cursor’s parallel sub-agents and isolated worktrees.

Official links:
- Skill directory: https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/best-of-n-solving
- Collection repository: https://github.com/spencerpauly/awesome-cursor-skills
- Cursor Skills documentation: https://cursor.com/docs/skills.md