npm package: @javisantos/prowess
Description: Model Context Protocol server for Prowess - Proven development workflows + Sequential Thinking for AI agents
Author: javisantos
Latest version: 1.1.4

# Prowess MCP Server

> **Extensible skill library for AI-powered development via Model Context Protocol**

Prowess is an MCP server that provides proven development workflows as executable "skills" for AI agents. It comes bundled with two comprehensive skill collections:

- 📚 **20+ workflow skills** from [Superpowers](https://github.com/obra/superpowers) by [Jesse Vincent (@obra)](https://github.com/obra)
- 🧠 **Sequential Thinking** from [Anthropic's MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)

**Plus, you can add your own skills** - both at the project level and personal level, making Prowess a growing, community-driven library of development best practices.

## What are Skills?

Skills are structured, reusable process documentation that guide AI agents through complex workflows:

- **Brainstorming**: Refine rough ideas collaboratively before coding
- **Test-Driven Development**: RED-GREEN-REFACTOR workflow with quality gates
- **Systematic Debugging**: Methodical root cause investigation
- **Sequential Thinking**: Dynamic problem-solving with thought revision and branching
- **Code Review**: Both requesting and receiving review feedback systematically
- ...and many more!

Each skill contains:
- Clear activation conditions ("Use when...")
- Step-by-step process documentation
- Checklists and quality checkpoints
- Examples and anti-patterns

## Features

- **🔧 Automatic Tool Invocation**: AI agents automatically invoke skills based on context
- **📝 Manual Prompts**: Skills also available as prompts for explicit loading
- **🎨 Three-tier Customization**: Override built-in skills with personal or project-specific versions
- **📦 Extensible**: Add community skills or create custom workflows
- **🔄 Live Updates**: File watcher detects skill changes in real-time
- **🌐 Universal Compatibility**: Works with VS Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client

## Installation

```bash
npm install -g @javisantos/prowess
```

Or use directly without installation:

```bash
npx @javisantos/prowess
```

## Setup

### VS Code (GitHub Copilot)

**Graphical Setup (Recommended - Works best):**

1. Click the **Tools** icon in the left sidebar (or bottom right)
2. Look for **MCP** section or **Model Context Protocol**
3. Click **"+ Add MCP Server"** or **"Add"**
4. Enter:
   - **Name**: `prowess`
   - **Command**: `npx`
   - **Args**: `-y @javisantos/prowess` (or `['-y', '@javisantos/prowess']`)
5. Click **Connect** or **Add**
6. VS Code will connect to Prowess automatically
7. Open Copilot Chat and start using skills!

**Manual JSON Setup:**

If you prefer editing the config file directly:

**Linux:**
```bash
# Edit ~/.config/Code/User/mcp.json
nano ~/.config/Code/User/mcp.json
```

Add to the `"servers"` object:
```json
"prowess": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@javisantos/prowess"]
}
```

**macOS:**
```bash
# Edit ~/Library/Application Support/Code/User/mcp.json
nano ~/Library/Application\ Support/Code/User/mcp.json
```

**Windows:**
```
%APPDATA%\Code\User\mcp.json
```

Add the same `"prowess"` entry to the `"servers"` object.

**Documentation**: [VS Code MCP Guide](https://code.visualstudio.com/docs/copilot/copilot-mcp)

### Claude Desktop

1. Open Claude Desktop config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add Prowess MCP configuration:

```json
{
  "mcpServers": {
    "prowess": {
      "command": "npx",
      "args": ["-y", "@javisantos/prowess"]
    }
  }
}
```

3. Restart Claude Desktop

**Documentation**: [Claude Desktop MCP Setup](https://modelcontextprotocol.io/quickstart/user)

### Windsurf (Codeium)

1. Open Windsurf
2. Click **Plugins** icon (top right in Cascade panel) or go to **Settings** → **Cascade** → **Plugins**
3. Click **"+ Add Plugin"** button
4. Configure manually:
   - **Name**: `prowess`
   - **Command**: `npx`
   - **Args**: `["-y", "@javisantos/prowess"]`
5. Click **Install** and refresh

Or edit `~/.codeium/windsurf/mcp_config.json` directly:

```json
{
  "mcpServers": {
    "prowess": {
      "command": "npx",
      "args": ["-y", "@javisantos/prowess"]
    }
  }
}
```

**Documentation**: [Windsurf MCP Guide](https://docs.windsurf.com/windsurf/cascade/mcp)

### Cursor

Cursor uses the same MCP configuration as VS Code:

1. Open Settings (JSON): **Cmd/Ctrl+,** then click **{}** icon
2. Add the same configuration as VS Code above
3. Restart Cursor

### Other MCP Clients

Prowess works with any MCP-compatible client. Use the standard MCP server configuration:

```json
{
  "command": "npx",
  "args": ["-y", "@javisantos/prowess"]
}
```

## Usage

### How Skills Work

Skills are automatically available as **tools** in your AI assistant. The LLM decides when to invoke them based on your request. No manual loading required!

### Sequential Thinking Tool

Prowess includes a **stateful Sequential Thinking tool** that enables complex, multi-step problem-solving:

**🔧 `sequential-thinking` (Interactive, Stateful Tool)**
- **Stateful**: Maintains thought history across invocations within a session
- **Interactive**: Each thought is a separate tool invocation
- **Dynamic**: Supports revision of previous thoughts and exploring alternative branches
- **Powered by**: Handler-based architecture for extensibility
- **Use for**: Complex multi-step analysis where you need to build thoughts incrementally

The tool allows you to:
- Build thoughts incrementally with numbering (Thought 1/N, Thought 2/N, etc.)
- Revise previous thoughts while keeping history
- Branch from any thought to explore alternatives
- Track progress and iterate toward solutions

### Example Workflows

**Brainstorming a new feature:**
```
You: "I need to add authentication to my app. Let's brainstorm the approach."
AI: [Automatically invokes prowess:brainstorming]
    "Let's explore this together. What authentication methods have you considered?"
    → Guides through: alternatives, trade-offs, security considerations, implementation plan
```

**Solving a complex problem (Interactive Sequential Thinking):**
```
You: "How can I optimize this database query that's timing out?"
AI: [Automatically invokes sequential-thinking tool]
    Thought 1/5: "Let me analyze the query structure..."
    Thought 2/5: "Identifying bottlenecks in JOIN operations..."
    Thought 3/5: "🔄 Revision of Thought 2 - actually, the issue is missing indexes..."
    Thought 4/5: "Testing hypothesis: adding composite index on (user_id, created_at)..."
    Thought 5/5: "✓ Verified: Query time reduced from 8s to 120ms"
```

**Debugging systematically:**
```
You: "My tests are failing randomly. Help me debug this."
AI: [Automatically invokes prowess:systematic-debugging]
    "Let's approach this systematically. First, what's the error message?"
    → Follows 4-phase framework: Investigation → Pattern Analysis → Hypothesis → Implementation
```

**Code review workflow:**
```
You: "Please review this pull request."
AI: [Automatically invokes prowess:requesting-code-review]
    → Checks for: test coverage, error handling, edge cases, documentation
    → Provides structured feedback with specific line references
```

### Manual Skill Loading (Advanced)

While skills are automatically invoked, you can also load them explicitly:

**List all available skills:**
```
Show me all available prompts from prowess
```

**Load a specific skill:**
```
Load the prowess:writing-plans prompt
```

## Adding Custom Skills

### Three-Tier Priority System

Prowess discovers skills from three locations with intelligent shadowing:

1. **🎯 Project skills** (`.prowess/skills/`) - **Highest priority**
   - Team-shared workflows specific to your project
   - Versioned with your code in Git
   - Automatically available to all team members
   - Override built-in skills with project-specific versions

2. **👤 Personal skills** (`~/.config/prowess/skills/`) - **Medium priority**
   - Your private workflows, reusable across all projects
   - Live in your home directory
   - Override built-in skills for your personal use
   - Not shared with team (unless you copy to project)

3. **📦 Built-in skills** (bundled with Prowess) - **Lowest priority**
   - 20+ proven workflows from Superpowers collection
   - Sequential Thinking from Anthropic
   - Always available as fallback

**Priority Resolution:** When you reference a skill (e.g., `writing-plans`), Prowess searches in order: project → personal → built-in. The **first match wins**. This lets you:
- Override any built-in skill with your own version
- Create project-specific variations of personal skills
- Force load specific versions with namespaces: `project:skill-name` or `prowess:skill-name`

### Why Use Project Skills?

Project skills are **game-changers for team consistency**:

✅ **No more tribal knowledge** - Workflows live in code, not in senior engineers' heads  
✅ **Automatic onboarding** - New team members get best practices from day one  
✅ **Version controlled** - Skills evolve with your project, tracked in Git  
✅ **AI-powered enforcement** - Copilot automatically applies your team's standards  
✅ **Override defaults** - Replace generic Prowess skills with company-specific versions

**Real-world use cases:**
- 🚀 Deployment procedures specific to your infrastructure
- 🧪 Testing requirements matching your CI/CD pipeline
- 📋 Code review checklists with company policies
- 🗄️ Database migration workflows for your stack
- 🔒 Security requirements for your compliance needs
- 📝 Documentation standards for your team

### Creating a Personal Skill

Example: Add a personal "api-design" skill for consistent API development:

```bash
mkdir -p ~/.config/prowess/skills/api-design
cat > ~/.config/prowess/skills/api-design/SKILL.md << 'EOF'
---
name: api-design
description: Use when designing REST APIs - ensures consistent endpoint structure, error handling, and documentation
---

# API Design Skill

Use this skill when designing new API endpoints.

## Checklist

- [ ] Use RESTful conventions (GET/POST/PUT/DELETE)
- [ ] Return consistent error format: `{"error": "message", "code": "ERROR_CODE"}`
- [ ] Include rate limiting headers
- [ ] Document with OpenAPI/Swagger
- [ ] Add request/response examples
- [ ] Version the API (v1, v2, etc.)
- [ ] Implement pagination for lists
- [ ] Add CORS headers if needed

## Example Response Format

\`\`\`json
{
  "data": {...},
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "v1"
  }
}
\`\`\`
EOF
```

Now when you say **"Design an API for user management"**, the AI automatically invokes your `api-design` skill!

### Creating a Project Skill

Project skills live in `.prowess/skills/` and are **automatically shared with your team** through Git.

**Basic structure:**

```bash
# Create skill directory in your project root
mkdir -p .prowess/skills/my-skill

# Create the skill definition with YAML frontmatter
cat > .prowess/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Custom Skill

[Your skill content here]

## Usage

[How to use this skill]

## Checklist

- [ ] Step 1
- [ ] Step 2
EOF

# Commit to Git - now your team has access!
git add .prowess/skills/my-skill/
git commit -m "feat: add my-skill for team"
```

### Supporting Files in Skills

Skills can include multiple files in their directory:

```bash
.prowess/skills/my-skill/
├── SKILL.md              # Main skill (required)
├── checklist.md          # Supporting documentation
├── scripts/
│   ├── helper.sh         # Helper scripts
│   └── validation.sh
└── templates/
    └── template.md       # Templates
```

Reference these files in your SKILL.md:
```markdown
See `checklist.md` for detailed checklist.
Run `./scripts/helper.sh` to validate.
```

### Creating Stateful Skills with Handlers

For advanced use cases requiring state management and custom tool schemas, you can create a **skill handler** - a TypeScript/JavaScript module that provides custom behavior:

```bash
.prowess/skills/my-stateful-skill/
├── SKILL.md              # Main skill documentation
└── handler.ts            # Custom handler (TypeScript/JavaScript)
```

**handler.ts example:**
```typescript
// Define the tool schema with custom input parameters
export const toolSchema = {
  inputSchema: {
    type: 'object',
    properties: {
      state_param: {
        type: 'string',
        description: 'Parameter for managing skill state'
      },
      action: {
        type: 'string',
        description: 'Action to perform'
      }
    },
    required: ['state_param', 'action']
  }
};

// Define the handler function
export async function process(input: Record<string, unknown>) {
  // Your custom logic here
  const result = await doSomething(input);
  
  return {
    content: [{
      type: 'text',
      text: `Result: ${result}`
    }],
    isError: false
  };
}
```

**When to use handlers:**
- ✅ Skills requiring **state persistence** across invocations
- ✅ **Custom tool schemas** with specialized parameters
- ✅ **Complex workflows** with multiple steps and state transitions
- ✅ **Integration** with external services or APIs

**Built-in example:** The `sequentialthinking` skill uses a handler to maintain thought history, enable revisions, and support branching.

## Bundled Skills

Prowess comes with **20+ proven development workflows** ready to use:

### 🧠 Problem-Solving & Planning
- **sequentialthinking** (interactive tool) - Anthropic's Sequential Thinking with stateful, multi-step problem analysis featuring revision and branching capabilities
- **sequential-thinking** (skill) - Complete Sequential Thinking documentation and process guide
- **brainstorming** - Refine rough ideas through collaborative questioning before coding
- **writing-plans** - Create comprehensive implementation plans with exact file paths and verification steps
- **executing-plans** - Execute plans in controlled batches with quality checkpoints

### 🐛 Debugging & Testing
- **systematic-debugging** - Methodical 4-phase debugging framework (Investigation → Pattern Analysis → Hypothesis → Implementation)
- **root-cause-tracing** - Trace errors to their source, validate at each layer
- **defense-in-depth** - Prevent bugs by validating data at system boundaries
- **test-driven-development** - RED-GREEN-REFACTOR workflow for robust code
- **testing-anti-patterns** - Avoid common testing mistakes (mocking misuse, test-only methods, etc.)
- **condition-based-waiting** - Replace flaky timeouts with state-based polling

### 👥 Code Review & Collaboration
- **requesting-code-review** - Prepare code for review with proper context and testing
- **receiving-code-review** - Apply review feedback with technical rigor, not blind compliance
- **sharing-skills** - Contribute new skills back to the community via pull requests

### ⚙️ Workflows & Process
- **using-prowess** - Core skill usage protocol (auto-loaded on first use)
- **subagent-driven-development** - Dispatch fresh subagents for parallel work
- **dispatching-parallel-agents** - Investigate multiple failures concurrently
- **using-git-worktrees** - Work on features in isolated git worktrees
- **finishing-a-development-branch** - Complete work with proper verification
- **verification-before-completion** - Ensure work is validated before claiming done
- **writing-skills** - Author new skills using TDD approach
- **testing-skills-with-subagents** - Test skills against rationalization before deployment

**See complete catalog**: [skills/](./skills/) directory or run `Show me all prowess skills`

### Community Skills

Want more skills? You can:
- **Browse community skills** - Check GitHub for `prowess-skill-*` repositories
- **Share your own skills** - Use the `sharing-skills` workflow to contribute via PR
- **Request new skills** - Open an issue describing your workflow

The goal is to build a comprehensive library of battle-tested development workflows!

## Development

### Build and Run

```bash
# Development mode (watch for changes)
npm run dev

# Build for production
npm run build

# Run built server
npm start

# Test with MCP Inspector
npm run inspect
```

### Logs

Server logs are written to `/tmp/prowess.log`:

```bash
tail -f /tmp/prowess.log
```

### Project Structure

```
prowess/
├── src/
│   ├── index.ts              # Server entry point
│   ├── skills-core.ts        # Skill discovery & parsing
│   ├── watcher.ts            # File watching
│   └── handlers/
│       ├── prompts.ts        # Prompt (skill) handlers
│       └── resources.ts      # Resource handlers
├── skills/                   # Bundled Superpowers skills
├── dist/                     # Compiled JavaScript (after build)
└── package.json
```

## Tool Mapping

When skills reference tools not in your environment, use these substitutions:

| Skill Tool | VS Code / MCP Client |
|------------|---------------------|
| `TodoWrite` | Your task management system |
| `Task` with subagents | `runSubagent` or @mention |
| `Skill` | MCP prompts/get |
| `Read`, `Write`, `Edit` | Native file tools |
| `Bash` | Terminal/command tools |

## Troubleshooting

### Server not appearing in VS Code

1. Check `.vscode/settings.json` has correct absolute path
2. Ensure `npm run build` completed successfully
3. Reload VS Code window (Cmd/Ctrl+Shift+P → "Developer: Reload Window")
4. Check Output panel → "GitHub Copilot Chat" for MCP errors

### Skills not loading

1. Verify skills exist: `ls skills/`
2. Check server logs: `tail -f /tmp/prowess.log`
3. Ensure SKILL.md files have proper YAML frontmatter
4. Try listing prompts to verify discovery

### Changes not detected

The file watcher monitors all skill directories. If changes aren't detected:

1. Check logs for watcher errors
2. Ensure you're editing `SKILL.md` files (not other files)
3. Try restarting the MCP server

## Contributing

We welcome contributions of **new skills**, **bug fixes**, and **documentation improvements**!

### Contributing a New Skill

1. **Use the `writing-skills` workflow** - It guides you through TDD for skills:
   ```
   "I want to create a new skill for [your workflow]"
   → AI invokes prowess:writing-skills
   → Helps you write, test, and refine the skill
   ```

2. **Test with subagents** before submitting:
   ```
   "Test my new skill with a subagent"
   → AI invokes prowess:testing-skills-with-subagents
   → Validates skill works under pressure
   ```

3. **Submit a pull request** using `sharing-skills`:
   ```
   "I want to contribute this skill upstream"
   → AI invokes prowess:sharing-skills
   → Guides through branch, commit, push, PR creation
   ```

### Skill Quality Guidelines

- **Clear trigger description** - When should the skill be used?
- **Actionable checklist** - What steps should be followed?
- **Real examples** - Show concrete usage patterns
- **Tested thoroughly** - Use `testing-skills-with-subagents` before submitting

### Development Setup

```bash
git clone https://github.com/javisantos/prowess.git
cd prowess
npm install
npm run build
npm run test:all
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines (if exists).

## Credits and Acknowledgments

This project stands on the shoulders of giants:

### [Superpowers](https://github.com/obra/superpowers) by [Jesse Vincent (@obra)](https://github.com/obra)
The complete skills library and development workflow methodology that forms the foundation of this MCP server. Superpowers pioneered the concept of composable, test-driven development skills for AI agents.

- **Author**: Jesse Vincent ([@obra](https://github.com/obra))
- **Website**: https://blog.fsck.com
- **Repository**: https://github.com/obra/superpowers
- **License**: MIT
- **Contribution**: All 20+ skills, workflow patterns, and the core philosophy of skill-based development

### [Sequential Thinking MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) by [Anthropic](https://anthropic.com)
The tool-based invocation pattern and dynamic problem-solving approach that inspired this MCP server's architecture.

- **Author**: Anthropic, PBC
- **Repository**: https://github.com/modelcontextprotocol/servers
- **License**: MIT
- **Contribution**: Tool invocation pattern, sequential thinking methodology, and MCP server architecture

### Special Thanks
- The [Model Context Protocol](https://modelcontextprotocol.io) team for creating an excellent protocol
- All contributors to Superpowers and Sequential Thinking
- The open-source community for continuous inspiration

**If this project helps you, consider:**
- ⭐ Starring [Superpowers](https://github.com/obra/superpowers)
- 💝 [Sponsoring Jesse Vincent](https://github.com/sponsors/obra)
- 🤝 Contributing back to the community

## License

MIT License - see LICENSE file

This project is a derivative work combining:
- Skills and workflows from [Superpowers](https://github.com/obra/superpowers) (MIT License)
- Architecture inspired by [Sequential Thinking MCP](https://github.com/modelcontextprotocol/servers) (MIT License)

## Links

- **Superpowers**: https://github.com/obra/superpowers
- **Sequential Thinking MCP**: https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking
- **Model Context Protocol**: https://modelcontextprotocol.io
- **MCP Specification**: https://spec.modelcontextprotocol.io
- **VS Code MCP Docs**: https://code.visualstudio.com/docs/copilot/copilot-mcp
- **Jesse Vincent's Blog**: https://blog.fsck.com

---

**Built with ❤️ for better AI-assisted development**