Skip to content

Distribute skills as a Claude Code plugin and via npx skills#17

Merged
charliek merged 1 commit into
mainfrom
plugin-distribution
May 24, 2026
Merged

Distribute skills as a Claude Code plugin and via npx skills#17
charliek merged 1 commit into
mainfrom
plugin-distribution

Conversation

@charliek
Copy link
Copy Markdown
Owner

@charliek charliek commented May 24, 2026

Summary

Makes the skills/ directory installable as agent skills through two channels, without moving or restructuring any skill files.

  • Claude Code plugin: new .claude-plugin/plugin.json and .claude-plugin/marketplace.json (self-contained, source: "./"). Install with /plugin marketplace add charliek/codelens then /plugin install codelens@codelens. Skills are namespaced codelens:<skill-name>.
  • Cross-agent: documented npx skills add charliek/codelens, which auto-discovers skills/ and installs into Claude Code plus 50+ other agents (Cursor, Codex, Copilot, Windsurf, ...). Needs no manifest.
  • Version lockstep: plugin.json hardcodes a version that Claude Code reads from main, so a new sync-version CI job commits version.txt and .claude-plugin/plugin.json back to main from the tag after each release (idempotent). scripts/set-version.sh is the shared setter, also used by the in-build step.

Install

npx skills add charliek/codelens

or

/plugin marketplace add charliek/codelens
/plugin install codelens@codelens

Notes

  • Repo-accurate values: license is Apache-2.0 and version is 0.0.1, matching the repo (not the MIT / 0.1.0 placeholders).
  • Validated: claude plugin validate . --strict passes; both manifests parse; set-version.sh is idempotent (byte-stable on a no-op run).
  • sync-version behavior: the bump lands just after the tag, so main HEAD is the installer-facing source of truth (the tag tree shows pre-bump version files). The bot push uses GITHUB_TOKEN, which does not re-trigger build.yml.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

  • New Features

    • Codelens is now available on the Claude Code plugin marketplace for installation.
    • Agent skills can be installed across multiple environments.
  • Documentation

    • Added installation instructions for codelens skills.
    • Updated development setup documentation with version management details.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 24, 2026

Warning

Review limit reached

@charliek, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 2 reviews/hour. Refill in 7 minutes and 31 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 329562c8-92d0-4241-ace7-df3edc7814d5

📥 Commits

Reviewing files that changed from the base of the PR and between 46b4fac and ff4778d.

📒 Files selected for processing (8)
  • .claude-plugin/marketplace.json
  • .claude-plugin/plugin.json
  • .github/workflows/release.yaml
  • CLAUDE.md
  • README.md
  • docs/development/setup.md
  • scripts/set-version.sh
  • version.txt
📝 Walkthrough

Walkthrough

This PR integrates codelens as a Claude Code plugin by adding plugin manifests, creating automated version synchronization between version.txt and the plugin metadata, updating the release workflow with a sync-version job, and documenting plugin installation and version management for users.

Changes

Claude Code Plugin Integration

Layer / File(s) Summary
Claude Code plugin manifests
.claude-plugin/marketplace.json, .claude-plugin/plugin.json
Defines the codelens plugin identity, metadata, version 0.0.1, description, author details, license, and keywords for marketplace discovery and Claude Code installation.
Version synchronization infrastructure
scripts/set-version.sh, .github/workflows/release.yaml
Introduces set-version.sh script to atomically update version.txt and .claude-plugin/plugin.json version field; integrates it into the release job and adds a new sync-version job that conditionally commits and pushes synchronized versions back to main after release.
Documentation and user guidance
README.md, CLAUDE.md, docs/development/setup.md
Adds "Install the skills" section to README with plugin marketplace and agent-based installation commands, updates CLAUDE.md with plugin version management explanation, and documents in setup.md how Claude Code reads the plugin manifest version from the default branch.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A plugin manifest springs to life,
With versions synced through release strife,
Marketplace and scripts align,
The codelens Claude Code now will shine! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: adding distribution support for skills via both Claude Code plugin and npx skills channels.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch plugin-distribution

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/release.yaml:
- Around line 69-73: Update the sync-version job to harden the checkout and push
steps: replace the unpinned actions/checkout@v6 reference with a pinned commit
SHA for actions/checkout, add with: persist-credentials: false to the Checkout
main step to avoid leaking the default GITHUB_TOKEN, and change the push command
that does git push origin HEAD:main to use an explicit tokenized remote URL
(e.g. git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}`@github.com/`${{
github.repository }} HEAD:main) so the push uses an explicit token rather than
persisted credentials.

In `@README.md`:
- Around line 55-57: Add the language identifier "bash" to the fenced code
blocks that contain the shell commands so markdown lint passes and formatting is
consistent; specifically update the fence around the block containing "npx
skills add charliek/codelens" and the block containing "/plugin marketplace add
charliek/codelens" and "/plugin install codelens@codelens" to start with ```bash
instead of ``` .
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4e7efcb9-5cc4-4bd8-9928-8c2a4cf74896

📥 Commits

Reviewing files that changed from the base of the PR and between a8bb1eb and 46b4fac.

📒 Files selected for processing (7)
  • .claude-plugin/marketplace.json
  • .claude-plugin/plugin.json
  • .github/workflows/release.yaml
  • CLAUDE.md
  • README.md
  • docs/development/setup.md
  • scripts/set-version.sh

Comment thread .github/workflows/release.yaml Outdated
Comment on lines +69 to +73
- name: Checkout main
uses: actions/checkout@v6
with:
ref: main
# Default persist-credentials keeps the GITHUB_TOKEN so we can push back.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

What is the current immutable commit SHA for actions/checkout v6, and does GitHub recommend pinning workflow actions by full commit SHA for supply-chain security?

💡 Result:

The immutable commit SHA for the initial release of actions/checkout v6.0.0 is 11bd71f01bbe51f23071765d1e4e75185345670c. GitHub strongly recommends pinning workflow actions by their full-length commit SHA to ensure supply-chain security [1]. Because tags (like v6) and branches are mutable, they can be repointed by repository owners or compromised accounts to different commits, potentially introducing malicious code into your workflows without warning [2][3][4][1]. Pinning to a full-length commit SHA provides an immutable reference that cannot be altered, effectively mitigating the risk of such supply-chain attacks [5][6][1]. To maintain the security benefits of pinning while still managing updates, it is common practice to use automated dependency management tools like Dependabot or Renovate, which can automatically open pull requests to update your pinned SHAs when new versions are released [5][2][7]. Additionally, GitHub provides organizational and repository-level policies that can be configured to require that all actions be pinned to a full-length commit SHA [1].

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the referenced portions of the workflow
sed -n '1,140p' .github/workflows/release.yaml | cat -n

Repository: charliek/codelens

Length of output: 3705


Harden the sync-version write-back job (pin actions/checkout + avoid persisted GITHUB_TOKEN credentials).

  • sync-version uses unpinned actions/checkout@v6 (supply-chain hardening: pin to a full commit SHA).
  • The job relies on checkout’s default credential persistence and then runs git push origin HEAD:main; disable persisted credentials and push using an explicit token URL.
🔒 Suggested hardening diff
   sync-version:
@@
       - name: Checkout main
-        uses: actions/checkout@v6
+        uses: actions/checkout@<PINNED_CHECKOUT_V6_SHA>
         with:
           ref: main
-          # Default persist-credentials keeps the GITHUB_TOKEN so we can push back.
+          persist-credentials: false
@@
       - name: Commit and push if the version files drifted
@@
-        run: |
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
           if [ -z "$(git status --porcelain version.txt .claude-plugin/plugin.json)" ]; then
             echo "version files already match ${GITHUB_REF_NAME}; nothing to commit"
             exit 0
           fi
@@
-          git push origin HEAD:main
+          git push "https://x-access-token:${GITHUB_TOKEN}`@github.com/`${GITHUB_REPOSITORY}.git" HEAD:main
🧰 Tools
🪛 zizmor (1.25.2)

[warning] 69-73: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)


[error] 70-70: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/release.yaml around lines 69 - 73, Update the sync-version
job to harden the checkout and push steps: replace the unpinned
actions/checkout@v6 reference with a pinned commit SHA for actions/checkout, add
with: persist-credentials: false to the Checkout main step to avoid leaking the
default GITHUB_TOKEN, and change the push command that does git push origin
HEAD:main to use an explicit tokenized remote URL (e.g. git push
https://x-access-token:${{ secrets.GITHUB_TOKEN }}`@github.com/`${{
github.repository }} HEAD:main) so the push uses an explicit token rather than
persisted credentials.

Comment thread README.md Outdated
Make the skills/ directory installable as agent skills through two channels
without moving or restructuring any skill files.

- Add .claude-plugin/plugin.json and .claude-plugin/marketplace.json so the four
  skills install as a Claude Code plugin (/plugin install codelens@codelens).
- Document both install channels in the README: cross-agent via npx skills, and
  the native Claude Code plugin.
- Add scripts/set-version.sh, the single setter for version.txt and the plugin
  manifest version.
- Add a sync-version CI job that commits version.txt and plugin.json back to main
  from the tag after each release, keeping the installer-facing plugin version in
  lockstep (idempotent).
- Record the version lockstep in CLAUDE.md and docs/development/setup.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@charliek charliek force-pushed the plugin-distribution branch from 46b4fac to ff4778d Compare May 24, 2026 05:28
@charliek charliek merged commit 4960b74 into main May 24, 2026
4 checks passed
@charliek charliek deleted the plugin-distribution branch May 24, 2026 05:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant