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

> Understand the PM Skills Marketplace structure. Learn how skills, commands, and plugins are organized using JSON manifests and Markdown for discoverable, code-free extensions.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: internals
- Published: 2026-06-15

---

**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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) file registers the plugin with the Claude Marketplace. This JSON manifest provides the metadata required for discovery, versioning, and attribution.

```json
{
  "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": "pawel@productcompass.pm",
    "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)](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)](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/grammar-check/SKILL.md) follows this strict format:

```markdown
---
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)](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) file illustrates the required front-matter structure:

```markdown
---
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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file.

## Marketplace Discovery Process

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

1. **Plugin registration** – Every [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) found in `.claude-plugin` directories registers a new plugin with the marketplace
2. **Skill indexing** – Each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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:

```python
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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) manifest that registers the offering with the Claude Marketplace.
- **Skills** are pure-text prompt templates stored as [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/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.