# PM Skills File Format Compatibility with AI Tools: Complete Guide > Learn about PM Skills file format compatibility with AI tools. Our markdown and JSON files ingest easily into AI assistants for seamless knowledge module execution. No compilation needed. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: how-to-guide - Published: 2026-06-30 --- **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`](https://github.com/phuryn/pm-skills/blob/main/.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-/` convention. Inside every plugin folder, the runtime expects a `pm-/.claude-plugin/plugin.json` manifest that declares the plugin metadata. For example, [`pm-toolkit/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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-/skills//SKILL.md`. Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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-/commands/.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/marketplace.json)) and the per-plugin manifests ([`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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. ```bash # 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`](https://github.com/phuryn/pm-skills/blob/main/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. ```bash # 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`](https://github.com/phuryn/pm-skills/blob/main/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. ```bash python3 validate_plugins.py ``` If all plugins follow the contract, the script returns: ```text All plugins validated – no errors. ``` The validator ensures that every `name` field in skill front-matter matches its folder, that every [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) whose front-matter `name` matches the user request. Because the `name` must equal the folder name—enforced by [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), which checks that every plugin manifest is valid JSON, that every skill folder contains a properly named [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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.