Integrating PM Skills with External Tools and APIs: A Complete Guide to Claude Code Plugin Extensions

The pm-skills repository enables external tool integration by declaring allowed-tools (such as Bash, Read, and Write) in command front-matter, which creates a sandboxed environment where Claude Code can execute shell commands, call REST APIs, and read repository files.

The phuryn/pm-skills repository is a collection of Claude Code plugins that exposes product-management knowledge through structured skills and executable commands. By leveraging the allowed-tools directive in command files, you can extend these PM workflows to interact with external APIs, CI pipelines, and data services without risking arbitrary code execution.

Understanding the PM Skills Architecture

The pm-skills codebase organizes functionality into self-contained plugins. Each plugin contains manifest files that register capabilities with Claude Code, skill definitions that encode domain knowledge, and command files that execute workflows.

Plugin Manifest Structure

The entry point for any integration is the plugin manifest. In /.claude-plugin/marketplace.json, the repository declares nine sub-plugins—including pm-toolkit, pm-product-discovery, and pm-ai-shipping—that Claude Code loads at startup. This top-level manifest describes the plugin collection's name, version, and description, allowing the platform to discover available commands and expose them to users.

Skills vs Commands

The architecture distinguishes between skills and commands. Skills are defined in SKILL.md files (such as /pm-toolkit/skills/grammar-check/SKILL.md) and contain YAML front-matter with name and description fields plus procedural documentation. Skills provide knowledge but do not execute code.

Commands, stored as *.md files (like /pm-ai-shipping/commands/ship-check.md), declare executable workflows. Their front-matter includes description, optional argument-hint, and the critical allowed-tools list that specifies which sandboxed operations the command may perform.

How External Integration Works

Integration with external tools relies on the sandboxed execution model defined in command front-matter.

The Allowed-Tools Sandbox

Every command file declares a whitelist of tools in its front-matter using the allowed-tools field. Common tools include:

• Read – Access files within the repository
• Write(path) – Create or modify files in specified directories
• Bash(command) – Execute shell commands with specific patterns
• Grep – Search source code for patterns
• Task – Run sub-tasks or child processes

For example, the security audit command at /pm-ai-shipping/commands/security-audit-static.md declares allowed-tools: Read, Grep, Bash(git log:*), Bash(find:*), permitting it to analyze repository history while restricting dangerous operations.

Execution Flow

When a user invokes a command like /ship-check, Claude Code performs the following steps:

1. Parses the command's front-matter and extracts the allowed-tools list
2. Creates a sandboxed environment containing only those capabilities
3. Executes the Markdown workflow, which may Read files, Grep for patterns, or Bash out to scripts that call external APIs via curl, aws cli, or similar tools
4. Collates results into a structured Markdown response

This sandboxed approach lets commands safely perform powerful operations—such as querying the Census API or uploading artifacts to S3—without exposing the system to unrestricted shell access.

Practical Integration Examples

You can extend pm-skills to integrate with external systems by creating new command files or modifying existing ones.

Fetching External API Data

To pull demographic data from the U.S. Census API for the user-personas skill, create a file at pm-market-research/commands/fetch-demographics.md:

---
description: Retrieve up-to-date demographic data from the Census API and store it in a local JSON file
argument-hint: "<state code>"
allowed-tools: |
  Read, Write(demographics/*.json), Bash(curl -s "https://api.census.gov/data/2024/acs/acs5?get=NAME,B01001_001E&for=state:${ARGUMENT}")
---

# /fetch-demographics -- Get Census Demographics

## Invocation

/fetch-demographics TX

## Workflow

1. The Bash tool runs `curl` against the Census API (the `${ARGUMENT}` placeholder is substituted with the user-provided state code).
2. The JSON response is written to `demographics/TX.json`.
3. A short summary is returned to the user.

Demographics for TX

Population: 29,730,311

This command declares the Bash tool to execute curl, retrieves external data, and uses the Write tool to persist results for downstream PM skills.

CI/CD Pipeline Integration

Integrate the /ship-check command into GitHub Actions to validate releases automatically. Create .github/workflows/ship.yml:

name: Ship Check
on:
  push:
    branches: [main]
jobs:
  ship:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Claude ship-check
        run: |
          echo "Running /ship-check"
          claudectl run /ship-check .
      - name: Upload Shipping Packet
        uses: actions/upload-artifact@v3
        with:
          name: shipping-packet
          path: reports/

The /ship-check command (defined in /pm-ai-shipping/commands/ship-check.md) uses its allowed-tools list—including Read, Grep, Glob, Task, and various Bash(git …) actions—to document the application, run static security audits (/security-audit-static), execute performance checks, and derive test coverage. Results are written to reports/ and archived by the CI workflow.

Programmatic API Consumption

Consume pm-skills commands from external Python scripts using the Claude Code HTTP API. The following example invokes the grammar-check skill:

import requests
import json

CLAUDE_ENDPOINT = "https://api.anthropic.com/v1/commands/grammar-check"
API_KEY = "YOUR_CLAUDE_API_KEY"

payload = {
    "arguments": {
        "OBJECTIVE": "Write a product announcement",
        "TEXT": "We have buisness and we want to launch."
    }
}

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

resp = requests.post(CLAUDE_ENDPOINT, headers=headers, data=json.dumps(payload))
print(resp.json()["response"])

This script sends arguments to the grammar-check command (backed by /pm-toolkit/skills/grammar-check/SKILL.md), allowing external applications to leverage the repository's PM knowledge base programmatically.

Key Source Files for Integration

When building external integrations, reference these authoritative source files in the phuryn/pm-skills repository:

• /.claude-plugin/marketplace.json – Top-level plugin manifest registering all nine sub-plugins
• /validate_plugins.py – Python validator ensuring plugin manifests and front-matter comply with Claude Code specifications
• /pm-toolkit/skills/grammar-check/SKILL.md – Example skill file showing YAML front-matter structure
• /pm-toolkit/commands/review-resume.md – Example command demonstrating workflow and output format
• /pm-ai-shipping/commands/ship-check.md – Complex command orchestrating documentation, security, and performance audits
• /pm-ai-shipping/commands/security-audit-static.md – Demonstrates allowed-tools usage with Bash and Grep operations
• /.github/workflows/tests.yml – CI workflow running the validator on every push

Summary

• pm-skills exposes product management knowledge through Claude Code plugins composed of SKILL.md definitions and executable command files.
• Integration with external tools occurs via the allowed-tools front-matter declaration, which creates a sandboxed environment for Read, Write, Bash, and Grep operations.
• Commands can call external APIs by declaring Bash(curl …) in their allowed-tools list, enabling connections to Census data, cloud services, or internal microservices.
• CI pipelines integrate by invoking commands like /ship-check through the claudectl CLI, allowing automated security audits and performance checks.
• External applications can consume skills programmatically via HTTP API calls, extending PM workflows beyond the Claude Code interface.

Frequently Asked Questions

How do I add a new external API integration to pm-skills?

Create a new command file in the appropriate plugin directory (e.g., pm-market-research/commands/) with a .md extension. Include a YAML front-matter block with description, argument-hint, and an allowed-tools list that declares Bash(curl …) or similar for your specific API endpoint. The command body should describe the workflow for handling the API response and storing data via the Write tool.

What security controls prevent arbitrary code execution?

The allowed-tools sandbox restricts each command to only the tools explicitly declared in its front-matter. If a command attempts to use a tool not listed—such as an unrestricted Bash command without arguments—Claude Code blocks the execution. The /validate_plugins.py script further enforces these constraints by validating that all command files declare proper front-matter and tool restrictions before the plugin loads.

Can I integrate pm-skills with private internal APIs?

Yes. Commands can declare Bash tools that call internal endpoints using authenticated curl commands or internal CLI tools like aws, gcloud, or kubectl. Store credentials using environment variables or secure secret management systems accessible to your Claude Code deployment, and reference them in your command workflows. The ship-check command demonstrates this pattern by using Bash(git log:*) to access repository history.

How do I validate that my integration command follows the plugin specification?

Run the /validate_plugins.py utility before committing changes. This script checks that your command file contains required front-matter fields (description, allowed-tools), validates cross-references between commands and skills, and ensures the JSON manifest structure is valid. The repository's /.github/workflows/tests.yml runs this validator automatically on every pull request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}