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 by Jesse Vincent (@obra)
• 🧠 Sequential Thinking from Anthropic's MCP

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

npm install -g @javisantos/prowess

Or use directly without installation:

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:

# Edit ~/.config/Code/User/mcp.json
nano ~/.config/Code/User/mcp.json

Add to the "servers" object:

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

macOS:

# 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

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:

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

3. Restart Claude Desktop

Documentation: Claude Desktop MCP Setup

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:

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

Documentation: Windsurf MCP Guide

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:

{
  "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:

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:

# 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:

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

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:

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

handler.ts example:

// 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/ 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

# 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:

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

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

See CONTRIBUTING.md for detailed guidelines (if exists).

Credits and Acknowledgments

This project stands on the shoulders of giants:

Superpowers by Jesse Vincent (@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)
• 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 by Anthropic

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 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
• 💝 Sponsoring Jesse Vincent
• 🤝 Contributing back to the community

License

MIT License - see LICENSE file

This project is a derivative work combining:

• Skills and workflows from Superpowers (MIT License)
• Architecture inspired by Sequential Thinking MCP (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