plugin-forge

Overview of plugin-forge skill

plugin-forge is a build-and-maintain skill for Claude Code plugin authors who want the right folder structure, manifest files, and marketplace registration without reinventing the workflow. The real job-to-be-done is not “write some JSON,” but “ship a plugin that is scaffolded correctly, versioned consistently, and installable in a marketplace-based workflow.”

Who plugin-forge is best for

Use the plugin-forge skill if you are:

• creating a new Claude Code plugin from scratch
• adding plugin parts such as commands/, agents/, skills/, or hooks/
• updating .claude-plugin/plugin.json and marketplace metadata together
• testing plugins locally before publishing
• maintaining a marketplace-style plugin repository with multiple plugins

It is especially useful for developers who want repeatable structure, not just one-off prompt output.

What makes plugin-forge different from a generic prompt

A generic prompt can draft a plugin skeleton, but plugin-forge adds practical guardrails:

• a defined plugin directory layout
• explicit manifest locations and field expectations
• a marketplace schema reference
• a workflow for local install and testing
• automation scripts for scaffolding and version bumping

That combination matters because the most common plugin failure is not code quality; it is inconsistent structure or mismatched metadata.

What the skill actually covers

The repository evidence shows plugin-forge is centered on:

• scripts/create_plugin.py for scaffolding a new plugin
• scripts/bump_version.py for synchronized version updates
• references/plugin-structure.md for folder and manifest layout
• references/marketplace-schema.md for marketplace entry rules
• references/workflows.md for creation, testing, and publishing flow

So this is more of an implementation guide plus helper tooling than a broad theory document.

When plugin-forge is a strong fit for Code Generation

plugin-forge for Code Generation is most useful when you want the model to generate files that must land in the correct plugin shape, for example:

• a new plugin skeleton with valid metadata
• a new command or skill inserted into an existing plugin
• updates to plugin.json plus matching marketplace entry changes
• release prep that includes semantic version bumps

If your main need is pure business logic inside an already-working plugin, plugin-forge helps less than a domain-specific coding skill.

How to Use plugin-forge skill

Install context for plugin-forge

The upstream SKILL.md does not publish its own install command, so installation depends on how you load skills in your environment. If you are using the repository’s skill bundle, a common pattern is:

npx skills add softaworks/agent-toolkit --skill plugin-forge

After that, use plugin-forge when your task is about plugin creation, manifests, marketplace registration, local testing, or version management.

Read these files first

For fast adoption, start in this order:

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

This path gives you the “what,” then the expected file layout, then the marketplace contract, then the runnable helpers.

What input plugin-forge needs from you

plugin-forge works best when you provide concrete repository and publishing context, not just “make me a plugin.” At minimum, specify:

• plugin name in kebab-case
• marketplace root path
• plugin purpose
• author name and email
• initial keywords
• category
• whether you need commands, agents, skills, hooks, or MCP config
• whether this is a new plugin or an update to an existing one

Without that information, the model can still draft files, but the output usually needs manual cleanup.

Turn a rough goal into a strong plugin-forge prompt

Weak prompt:

Create a Claude Code plugin for my project.

Stronger prompt:

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

The second prompt gives plugin-forge enough information to produce files that are much closer to usable.

Use the scaffolding script when you want speed

If you already know your metadata, use the helper script instead of manually building the initial tree:

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

This is the fastest path when you care more about correct setup than custom hand-crafted scaffolding.

Use the version script to avoid manifest drift

One of the most practical parts of plugin-forge usage is synchronized versioning. The skill includes scripts/bump_version.py to update both:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Example:

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

This matters because version mismatch across those files is a common maintenance mistake.

Follow the actual plugin-forge workflow

A practical plugin-forge guide is:

1. scaffold the plugin
2. inspect generated plugin.json
3. verify marketplace entry in .claude-plugin/marketplace.json
4. add components such as commands or skills
5. test locally via marketplace install flow
6. iterate
7. bump version before release

That workflow is more reliable than asking the model for everything in one huge prompt.

Local testing flow to plan for early

The references include a concrete local testing path:

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

That means you should design prompts so plugin-forge outputs installable paths and metadata, not just descriptive files. If the source path or plugin name is inconsistent, testing breaks immediately.

Key files plugin-forge will often modify

In real usage, expect plugin-forge to create or edit:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

That scope is useful for planning review, because plugin-forge is often a multi-file change generator.

Practical tips that improve plugin-forge output quality

Ask plugin-forge to:

• preserve existing plugin names and paths exactly
• keep all identifiers in kebab-case
• show both plugin manifest and marketplace entry together
• explain any required fields it could not infer
• separate “generated files” from “manual follow-up”
• validate that versions and names match across manifests

These requests reduce the chance of attractive but non-installable output.

plugin-forge skill FAQ

Is plugin-forge worth using if I can already prompt well?

Yes, if your main risk is structural correctness. The plugin-forge skill is more useful than an ordinary prompt when you need consistent manifests, marketplace entries, and directory layout. If you only need help writing one command file inside an existing plugin, the advantage is smaller.

Is plugin-forge beginner-friendly?

Mostly yes. plugin-forge gives beginners a concrete path through plugin creation and testing. The catch is that beginners still need to understand their marketplace root, naming conventions, and what components they actually want. It helps with structure more than with product design.

When should I not use plugin-forge?

Skip plugin-forge if:

• you are not building a Claude Code plugin
• you do not use marketplace-style distribution
• you only want generic Python or JavaScript code generation
• your repository has a custom plugin layout that intentionally differs from the documented structure

In those cases, plugin-forge may push you toward the wrong shape.

Does plugin-forge handle publishing automatically?

Not fully. The skill covers the prep work well: scaffolding, manifests, marketplace registration, local testing guidance, and version updates. But it is not an end-to-end release platform. You still need to review files, test locally, and run your own publishing or distribution process.

What is the biggest adoption blocker?

Usually missing repository context. plugin-forge assumes you know where the marketplace root lives and how your plugin should be categorized. If you cannot answer those questions, the output will still be draft-quality rather than production-ready.

How does plugin-forge compare with editing manifests by hand?

Manual edits work for one-off changes, but plugin-forge is better when you want repeatability or need to avoid drift between plugin.json and marketplace.json. The included scripts are the clearest practical advantage.

How to Improve plugin-forge skill

Give plugin-forge repository-aware inputs

The best improvement is to supply exact paths and current files. Instead of asking for “a version bump,” say:

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

That pushes the skill toward verifiable changes rather than generic advice.

Ask for file-by-file output, not just a summary

plugin-forge performs better when you ask for concrete deliverables:

• full plugin.json
• exact marketplace entry
• proposed directory tree
• README starter
• follow-up commands to test locally

This is especially important for plugin-forge for Code Generation, where the value comes from ready-to-apply files.

Prevent the most common failure modes

Watch for these issues in plugin-forge output:

• plugin name differs across files
• marketplace source path does not match actual folder layout
• version updated in one manifest but not the other
• optional components are referenced in metadata but not created
• generated structure omits .claude-plugin/plugin.json

A quick review against references/plugin-structure.md and references/marketplace-schema.md catches most of them.

Use a two-pass workflow for better results

A strong plugin-forge guide in practice is:

1. first pass: generate structure and manifests
2. second pass: generate plugin components and README improvements

Trying to do scaffolding, business logic, docs, testing setup, and publishing notes in one prompt often lowers quality. plugin-forge is strongest when structure comes first.

Iterate after the first output with targeted corrections

Do not just say “fix this.” Give precise repair instructions, for example:

• “Regenerate marketplace.json entry so source points to ./plugins/schema-audit.”
• “Add skills/ to the tree and keep manifest fields unchanged.”
• “Update only version fields; do not rewrite descriptions or keywords.”
• “Align the plugin name to kebab-case everywhere.”

That kind of constrained iteration makes plugin-forge much more reliable.

Pair plugin-forge with the reference docs, not instead of them

The best way to improve plugin-forge output is to make it cite or follow the repository references explicitly. In prompts, mention:

• references/plugin-structure.md for directory expectations
• references/marketplace-schema.md for marketplace fields
• references/workflows.md for install and testing flow

This keeps the skill anchored to the repo’s actual conventions instead of falling back to generic plugin assumptions.