Skill To Plugin — Claude Code Guide

From skill to plugin is workflow evolution

A skill describes one repeatable procedure. A plugin adds delivery, installation, versioning, namespace, and maintenance rules. A plugin is therefore not automatically better than a local skill; it is justified when the workflow has become a team asset.

A mature process usually evolves as: one-off prompt → CLAUDE.md or rules → repeatable skill → shared plugin.

When packaging is justified

• The same workflow is needed in several repositories.
• Manual copying already creates divergent versions.
• Other people use the skill.
• Compatibility and a specific workflow version must be recorded.
• Colleagues need repeated installation guidance.
• Changes require a changelog and documentation.

Minimal plugin structure

plugins/
└── team-review-kit/
    ├── plugin.yaml
    ├── README.md
    ├── CHANGELOG.md
    └── skills/
        ├── issue-analysis/
        │   └── SKILL.md
        └── pr-review/
            └── SKILL.md

What the package should describe

1. Name, version, and purpose.
2. Namespace and component list.
3. Installation instructions and scope.
4. Constraints, compatibility, and required permissions.
5. Disable, update, and rollback procedures.
6. Usage examples and change history.

Do not package chaos

A plugin only distributes a workflow. If the local skill is unstable, lacks a verifiable result, or needs repeated oral explanations, stabilize it in one project first. Packaging should follow maturity, not imitate it.