Superpowers MCP Server

Instructions

Implementation Reference

• superpowers-mcp.js:256-286 (handler)

  Executes the 'use_skill' tool: resolves the skill path, reads and processes the SKILL.md file (extract frontmatter, strip it), constructs a header, and returns the skill content as text.

    if (name === 'use_skill') {
      const { skill_name } = args;
  
      const resolved = resolveSkillPath(skill_name);
  
      if (!resolved) {
        return {
          content: [{
            type: 'text',
            text: `Error: Skill "${skill_name}" not found.\n\nRun find_skills to see available skills.`
          }]
        };
      }
  
      const fullContent = fs.readFileSync(resolved.skillFile, 'utf8');
      const { name: skillDisplayName, description } = extractFrontmatter(resolved.skillFile);
      const content = stripFrontmatter(fullContent);
      const skillDirectory = path.dirname(resolved.skillFile);
  
      const skillHeader = `# ${skillDisplayName || skill_name}
  # ${description || ''}
  # Supporting tools and docs are in ${skillDirectory}
  # ============================================`;
  
      return {
        content: [{
          type: 'text',
          text: `${skillHeader}\n\n${content}`
        }]
      };
    }

• superpowers-mcp.js:197-210 (registration)

  Registers the 'use_skill' tool in the list of available tools, including its name, description, and input schema.

  {
    name: 'use_skill',
    description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques.',
    inputSchema: {
      type: 'object',
      properties: {
        skill_name: {
          type: 'string',
          description: 'Name of the skill to load (e.g., "superpowers:brainstorming", "my-custom-skill")'
        }
      },
      required: ['skill_name']
    }
  }

• superpowers-mcp.js:134-165 (helper)

  Helper function used by 'use_skill' to resolve a skill name to its actual SKILL.md file path, prioritizing personal skills unless prefixed with 'superpowers:'.

  function resolveSkillPath(skillName) {
    const forceSuperpowers = skillName.startsWith('superpowers:');
    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
  
    // Try personal skills first (unless explicitly superpowers:)
    if (!forceSuperpowers && personalSkillsDir) {
      const personalPath = path.join(personalSkillsDir, actualSkillName);
      const personalSkillFile = path.join(personalPath, 'SKILL.md');
      if (fs.existsSync(personalSkillFile)) {
        return {
          skillFile: personalSkillFile,
          sourceType: 'personal',
          skillPath: actualSkillName
        };
      }
    }
  
    // Try superpowers skills
    if (superpowersSkillsDir) {
      const superpowersPath = path.join(superpowersSkillsDir, actualSkillName);
      const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
      if (fs.existsSync(superpowersSkillFile)) {
        return {
          skillFile: superpowersSkillFile,
          sourceType: 'superpowers',
          skillPath: actualSkillName
        };
      }
    }
  
    return null;
  }