PM Skills File Format Compatibility with AI Tools: Complete Guide

The PM Skills repository stores every skill as a markdown file with YAML front-matter and every plugin as a JSON manifest, so any AI assistant that can read text files can ingest and execute the knowledge modules without compilation or modification.

If you are evaluating how phuryn/pm-skills integrates with AI assistants, the short answer is portability. The entire codebase is built on conventions from the Claude-compatible skill format, yet it remains pure markdown and JSON, which makes it readable by Claude Code, Claude Cowork, Gemini, Cursor, Kiro, and any future agent that parses standard text files.

Architecture of the PM Skills Plugin System

The repository is organized into layers, each with a strict file naming contract that allows AI runtimes to discover content automatically.

Global Marketplace Manifest

The top-level configuration lives in .claude-plugin/marketplace.json. This file lists all nine plugins, their versions, and their repository locations. When you register the marketplace with an AI tool, this JSON file is the first thing parsed.

Plugin Folders and Manifests

Each plugin resides in its own folder following the pm-<name>/ convention. Inside every plugin folder, the runtime expects a pm-<name>/.claude-plugin/plugin.json manifest that declares the plugin metadata. For example, pm-toolkit/.claude-plugin/plugin.json defines the toolkit plugin that bundles resume review, NDA analysis, and grammar skills.

Skill Files and Front-Matter Contract

Individual skills are stored in pm-<name>/skills/<skill>/SKILL.md. Every SKILL.md file begins with YAML front-matter containing at least name and description. The name field must identically match the parent folder name—review-resume for skills/review-resume/—so the AI runtime can auto-resolve a skill when a user types its name. This deterministic mapping is enforced by validate_plugins.py.

The front-matter is loaded eagerly by the AI for auto-completion, while the markdown body is streamed on demand when the skill is actually invoked.

Command Definitions

Workflow triggers live in pm-<name>/commands/<command>.md. A command defines the slash-command syntax, a description, and an argument hint. Commands do not contain logic; they reference skills by name only. For example, pm-toolkit/commands/review-resume.md invokes the review-resume skill by name, keeping the interface decoupled from implementation.

How PM Skills Achieves Universal AI Compatibility

Because the format avoids proprietary binaries or custom DSLs, the repository satisfies four compatibility guarantees that make it universally portable.

Markdown-Only Skill Definitions

Every skill is a single SKILL.md file. There are no binary assets, no compiled extensions, and no environment variables to configure. Any AI system that can clone a GitHub repo and read *.md files can load the skill body directly.

Enforced Front-Matter Naming Contract

The validator script validate_plugins.py guarantees that the name key inside a skill's front-matter matches its directory name. This contract allows the AI runtime to map a user utterance like "review-resume" to the exact file path pm-toolkit/skills/review-resume/SKILL.md without a lookup index.

Decoupled Commands and Skills

Commands reference skills only by string name, never by code import or internal ID. This means a command file such as pm-toolkit/commands/review-resume.md can be copied to another AI platform—Gemini CLI, OpenCode, or a custom agent—and it will still successfully trigger the identically named skill.

Platform-Agnostic JSON Manifests

Both the global marketplace manifest (.claude-plugin/marketplace.json) and the per-plugin manifests (plugin.json) conform to the Claude Plugin specification, which serves as the de-facto standard for AI-assistant extensions. Other agents read the same directory layout, making the structure readable even when the underlying runtime changes.

Using PM Skills with Claude Code and Claude Cowork

You can install the entire marketplace or individual plugins through the Claude CLI.

# Install the full PM Skills marketplace

claude plugin marketplace add phuryn/pm-skills

# Install only the pm-toolkit plugin

claude plugin install pm-toolkit@pm-skills

# Invoke the resume review skill

claude "review-resume: Please review my product-manager resume"

In Claude Cowork, the workflow is point-and-click:

1. Open Customize → Browse plugins → Personal → +.
2. Add the phuryn/pm-skills marketplace.
3. Type /review-resume in the chat box and attach a file.
4. Cowork executes the command, which calls the review-resume skill defined in pm-toolkit/skills/review-resume/SKILL.md.

Porting PM Skills to Other AI Assistants

Because skills are pure markdown, migrating them to another platform requires only a file copy.

# Create a local skill directory for Gemini CLI

mkdir -p .gemini/skills

# Copy the skill folder directly

cp -r pm-toolkit/skills/review-resume/* .gemini/skills/

# Gemini can now load and execute the same markdown guide

gemini "review-resume: Analyze attached resume"

No code changes are required. The same SKILL.md body and front-matter that Claude consumes are valid for any assistant that parses markdown.

Validating File Format Compliance

Before publishing or syncing changes, run the repository's validator to catch naming mismatches or invalid JSON.

python3 validate_plugins.py

If all plugins follow the contract, the script returns:

All plugins validated – no errors.

The validator ensures that every name field in skill front-matter matches its folder, that every plugin.json is schema-compliant, and that the marketplace manifest correctly references existing plugin paths.

Summary

• PM Skills stores every module as plain text: markdown for skills and commands, JSON for manifests.
• The front-matter contract (name equals folder name) lets AI runtimes auto-discover skills without a central registry.
• Commands are decoupled from skills, so they transfer across AI platforms without modification.
• The validator validate_plugins.py enforces format compliance automatically.
• Because there are no dependencies, binaries, or environment variables, the repository works out-of-the-box with Claude, Gemini, Cursor, Kiro, and any future agent that reads text files.

Frequently Asked Questions

Can PM Skills be used with AI assistants other than Claude?

Yes. The repository is advertised as "Skills compatible with other AI assistants" because every file is pure markdown or JSON. As long as the target tool can read *.md and *.json and parse YAML front-matter, it can load the skills. The review-resume skill, for example, can be copied directly into a Gemini CLI directory and executed without edits.

What file format does PM Skills use for skill definitions?

Skills are defined in a single SKILL.md file per skill. The file starts with YAML front-matter containing metadata such as name and description, followed by a standard markdown body that contains the procedural guide. This format is intentionally limited to universal text standards to maximize compatibility.

How does the AI know which skill to load?

The AI runtime scans all plugin manifests, then searches skill folders for a SKILL.md whose front-matter name matches the user request. Because the name must equal the folder name—enforced by validate_plugins.py—the mapping is deterministic. The runtime shows the description in auto-complete and streams the markdown body into the model context upon invocation.

Is there a way to verify that PM Skills files are correctly formatted?

Yes. The repository includes validate_plugins.py, which checks that every plugin manifest is valid JSON, that every skill folder contains a properly named SKILL.md, and that the front-matter name matches the directory name. Running python3 validate_plugins.py from the repository root confirms that the file structure adheres to the format required by AI runtimes.

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