How Skills, Commands, and Plugins Are Structured in the PM Skills Marketplace

The PM Skills Marketplace is a flat, file-based extension system where plugins package skills as reusable prompt templates and commands as CLI-style entry points, all discoverable through JSON manifests and Markdown definitions without requiring compiled code.

The phuryn/pm-skills repository demonstrates how Skills, Commands, and Plugins are structured in the PM Skills Marketplace using a minimalist, human-readable architecture. This three-layer system allows Claude agents to discover and execute productivity tools through simple configuration files rather than compiled binaries.

The Plugin Package Layout

Every marketplace offering resides in a self-contained top-level directory (e.g., pm-toolkit/, pm-product-strategy/) that functions as a standalone plugin package. Each package follows a consistent internal structure that separates configuration from execution logic.

Plugin Manifest Configuration

At the root of every package, the .claude-plugin/plugin.json file registers the plugin with the Claude Marketplace. This JSON manifest provides the metadata required for discovery, versioning, and attribution.

{
  "name": "pm-toolkit",
  "version": "2.0.0",
  "description": "PM utility skills: resume review, NDA drafting, privacy policy generation, and grammar/flow checking.",
  "author": {
    "name": "Paweł Huryn",
    "email": "[email protected]",
    "url": "https://www.productcompass.pm"
  },
  "keywords": ["product-management","resume","legal","nda","privacy-policy","copywriting"],
  "homepage": "https://www.productcompass.pm",
  "license": "MIT"
}

Source: [pm-toolkit/.claude-plugin/plugin.json](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/.claude-plugin/plugin.json)

Skill Definitions

Skills reside in the /**/skills/ directory as Markdown files containing YAML front-matter and detailed instruction blocks. Each skill is a pure text template—no executable code—that defines how Claude should process specific tasks.

A skill file like [pm-toolkit/skills/grammar-check/SKILL.md](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/grammar-check/SKILL.md) follows this strict format:

---
name: grammar-check
description: "Identify grammar, logical, and flow errors in text and suggest targeted fixes without rewriting the entire text."
---

# Grammar and Flow Checking

## Purpose

Analyze the provided text for grammatical errors, logical inconsistencies, and flow issues.

## Process

### Step 1: Read the text carefully

### Step 2: Identify specific issues

...

Key conventions within skill files include:

• Input arguments declared using $ARGUMENT syntax (e.g., $OBJECTIVE, $TEXT)

• Sectioned workflows using ## Purpose, ## Process, and ### Step N headings

• Explicit output formats defined as bullet lists or markdown sections

• Optional verification checklists at the end for self-validation

Command Wrappers

Commands expose user-facing entry points through the /**/commands/ directory. Each command is a Markdown file that maps slash-syntax invocations (e.g., /review-resume) to underlying skills.

The [pm-toolkit/commands/review-resume.md](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) file illustrates the required front-matter structure:

---
description: Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback
argument-hint: "<resume as text or file>"
---

# /review-resume -- PM Resume Review

## Workflow

1. Accept the resume file or text input
2. Load the resume-review skill
3. Generate a scorecard table...

Command files typically contain invocation blocks showing exact slash syntax, workflow steps mirroring the skill instructions, scorecard tables for structured output, and next-step suggestions linking to other commands.

Decoupling Commands from Skills

Commands do not embed skill logic directly. Instead, they reference skills by name, creating a loose coupling that allows a single skill to serve multiple commands. For example, the grammar-check skill supports both /proofread and /tailor-resume commands without code duplication.

When a user invokes /review-resume, Claude loads the corresponding command file, extracts the skill reference, then retrieves and executes the instructions from the associated SKILL.md file.

Marketplace Discovery Process

When Claude scans the repository, it executes a three-phase discovery process:

1. Plugin registration – Every plugin.json found in .claude-plugin directories registers a new plugin with the marketplace
2. Skill indexing – Each SKILL.md file parsed under /**/skills/ registers a skill keyed by its name field
3. Command binding – Markdown files in /**/commands/ register as slash-commands that point to specific skills

This structure enables the marketplace UI to list "PM Toolkit" with its four to five visible commands while maintaining access to the underlying skill set.

Programmatic Exploration

You can interact with the marketplace structure using standard filesystem operations. The following Python script demonstrates how to enumerate all commands for a specific plugin by parsing the manifest and command files:

import pathlib
import json

# Path to the plugin root

plugin_root = pathlib.Path("pm-toolkit")

# Load plugin manifest

with open(plugin_root / ".claude-plugin" / "plugin.json") as f:
    manifest = json.load(f)

print(f"Plugin: {manifest['name']} (v{manifest['version']})")
print("Available commands:")

# Iterate over command markdown files

for cmd_file in (plugin_root / "commands").glob("*.md"):
    # First line of the file contains the description front‑matter

    with cmd_file.open() as f:
        first_line = f.readline().strip()
    # Extract the description from the front‑matter

    description = first_line.split("description:")[1].strip().strip('"')
    print(f" • /{cmd_file.stem} – {description}")

Running this script against the pm-toolkit directory outputs:

Plugin: pm-toolkit (v2.0.0)
Available commands:
 • /review-resume – Comprehensive PM resume review against 10 best practices — structure, impact metrics, keywords, and actionable feedback
 • /tailor-resume – Tailor a resume to a specific job posting
 • /proofread – Grammar and flow checking of any text
 • /privacy-policy – Generate a privacy policy from a brief description
 • /draft-nda – Draft a non‑disclosure agreement

Summary

• Plugin packages are self-contained directories with a .claude-plugin/plugin.json manifest that registers the offering with the Claude Marketplace.
• Skills are pure-text prompt templates stored as SKILL.md files with YAML front-matter defining name and description, utilizing $ARGUMENT syntax for input handling.
• Commands are Markdown wrappers in the commands/ directory that expose slash-syntax entry points and reference skills by name rather than embedding their logic.
• Decoupled architecture allows single skills to power multiple commands, promoting code reuse across the marketplace.
• Zero-compilation design enables immediate deployment and auditing through human-readable JSON and Markdown files.

Frequently Asked Questions

What file format defines a plugin in the PM Skills Marketplace?

Each plugin is defined by a JSON manifest file located at .claude-plugin/plugin.json within the plugin's root directory. This file contains required metadata including the plugin's name, version, description, author details, searchable keywords, and license information.

How do Skills accept user input in the PM Skills Marketplace?

Skills declare input parameters using the $ARGUMENT syntax within the instruction text (e.g., $TEXT or $OBJECTIVE). When a command invokes the skill, Claude substitutes these placeholders with the actual values provided by the user either through the slash-command arguments or interactive prompts.

Can one Skill be used by multiple Commands in the PM Skills Marketplace?

Yes. The architecture explicitly decouples commands from skills, allowing a single SKILL.md file to be referenced by multiple command files. For example, the grammar-check skill serves both the /proofread and /tailor-resume commands without requiring duplicated logic.

Does the PM Skills Marketplace require any build or compilation steps?

No. The marketplace operates entirely on static files—JSON manifests and Markdown definitions—that Claude parses at runtime. This file-based approach eliminates build steps, makes the repository immediately forkable and extensible, and allows version control systems to track changes to prompt logic with standard diff tools.

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