promote-skill · v1.0.0 · 2026-09-20 · sha256 a1373bb5d4a91f20
promote-skill v1.0.0A
Immutable. This exact content never changes and is served at /api/v1/blob/a1373bb5d4a91f20.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_yctjdnpc5zx3nhwf/a1373bb5d4a91f20767e4aca493a9e98c80e110d8e499c3be188fbad786cca15.json
Then /plugin install promote-skill@markdownregistry-yctjdnpc5zx3nhwf in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: promote-skill description: >- Move a tested personal agent skill into a shared skills repository, check for overlap, normalize metadata, update the catalog and release files, validate the package, and publish it through a reviewable branch. Use when the user asks to promote, publish, share, or contribute a global skill. license: MIT metadata: author: jcottam version: "1.0.0" --- # Promote Skill Promote a tested personal skill into a shared repository without creating duplicate skills or losing its working version. ## Required inputs Identify: - The source skill directory - The destination repository - The destination category - The repository's default branch and contribution rules Personal skills commonly live in `~/.cursor/skills/` or `~/.agents/skills/`. Read the destination repository's `AGENTS.md`, `CONTRIBUTING.md`, and existing skill examples before making changes. ## 1. Check for overlap Search personal and repository skills by: - Skill name - Description and trigger phrases - Main workflow steps - Commands and safety rules Classify similar skills as: - **Duplicate**: same purpose and workflow - **Extension**: one skill is a more complete version of another - **Adjacent**: related but has a different outcome Recommend merging or replacing duplicates. Keep adjacent skills separate with clear trigger boundaries. Get the user's approval before changing the proposed publication set. ## 2. Prepare the repository Start from an updated default branch and create a focused feature branch: ```bash git fetch origin git checkout <default-branch> git pull --ff-only origin <default-branch> git checkout -b feature/add-<skill-name>-skill ``` Do not work directly on the default branch unless the user explicitly asks. ## 3. Normalize the skill Copy the complete skill directory, including needed scripts, references, and assets, into: ```text skills/<category>/<skill-name>/ ``` Use repository metadata conventions. For Agent Resources: ```yaml --- name: skill-name description: What the skill does and when it should trigger. license: MIT metadata: author: jcottam version: "1.0.0" --- ``` Keep `SKILL.md` focused and under 500 lines. Remove machine-specific paths, secrets, temporary files, and private project details. ## 4. Update release files Update every catalog used by the destination repository: - Add the skill path to `.claude-plugin/plugin.json` - Add the skill to the correct table in `README.md` - Add a new entry to `CHANGELOG.json` Use the plugin manifest version as the release source of truth: - Patch: fixes only - Minor: new skills or improvements - Major: breaking changes The newest changelog version must match the plugin manifest version. Keep skill versions independent in each skill's metadata. ## 5. Validate Check all of the following: - YAML frontmatter parses and contains required metadata - The directory name matches the skill name - `plugin.json` is valid JSON - The plugin skills array has no duplicate paths - Every listed skill path exists - The README link points to the new `SKILL.md` - Referenced scripts and files exist - No secrets or personal project data are included - The working tree contains only intended changes Run repository checks when available. Review the final diff before publishing. ## 6. Publish Commit with a concise message, push the feature branch, and open a pull request that lists: - Skills added or replaced - Overlap decisions - Version changes - Validation performed Do not delete the personal source skill until the repository change is merged and the installed repository version is confirmed. ## Final report Report: - Published skill path - Replaced or retired skills - Manifest and changelog version - Validation results - Pull request URL - Any local cleanup still needed