Updated claude-code-skill-plugin.md

[billbrietstout]

CodeGuard Claude Code Plugin

Overview

Project CodeGuard ships as a Claude Code plugin that bundles a security-focused Agent Skillsoftware-security built from the project's unified security rules. Once installed, Claude Code activates the skill automatically when generating or reviewing code, applying CodeGuard's secure-by-default guidance without per-prompt instructions.

This guide covers installation, what's inside, day-to-day usage, and team deployment.

---

What is an Agent Skill?

Agent Skills are model-invoked capabilities. Claude consults a skill's SKILL.md when the task context matches its description, then follows the embedded workflow and references the bundled rule files. The CodeGuard skill exposes 23 security rules (3 always-apply + 20 context-specific) and tells Claude when to apply each.

For background on the skill system itself, see Anthropic's Skills documentation.

---

Prerequisites

• Claude Code 1.0.33 or later. Check with claude --version. Earlier versions don't have /plugin. Update via Homebrew (brew upgrade claude-code), npm (npm update -g @anthropic-ai/claude-code), or your installer.
• Basic familiarity with Claude Code slash commands.

---

Installation

1. Add the Project CodeGuard marketplace

From inside Claude Code:

/plugin marketplace add cosai-oasis/project-codeguard

This registers the catalog but installs nothing yet. (Shortcut: /plugin market add ... also works.)

2. Install the security plugin

/plugin install codeguard-security@project-codeguard

The plugin name is codeguard-security; the marketplace name is project-codeguard. By default this installs to user scope (all your projects). To choose a different scope, run /plugin, go to the Discover tab, press Enter on codeguard-security, and pick:

• User scope for yourself across all projects (default)
• Project scope shared with everyone who trusts this repo (writes to .claude/settings.json)
• Local scope for yourself, only in this repo

3. Activate without restarting

/reload-plugins

Claude Code reloads plugins and reports counts of skills, agents, hooks, and MCP servers. The CodeGuard skill is now active.

4. Verify

Run /plugin and switch to the Installed tab. You should see codeguard-security@project-codeguard listed and enabled.

Trust note. Plugins and marketplaces can execute arbitrary code with your user privileges. Only install from sources you trust; review the repository before adding the marketplace.

---

How the skill works

When you write or review code, Claude reads SKILL.md and decides which CodeGuard rules apply to the current task.

When the skill activates

Automatically, when Claude is:

• Writing new code in any supported language
• Reviewing or modifying existing code
• Implementing authentication, cryptography, or other security-sensitive features
• Working with user input, databases, APIs, or external services
• Configuring cloud infrastructure, CI/CD pipelines, or containers
• Handling sensitive data, credentials, or cryptographic operations

Workflow Claude follows

1. Initial security check. Claude identifies the language, the security domains involved (auth, crypto, file handling, etc.), and whether credentials are in scope.
2. Code generation. Claude applies secure-by-default patterns from the relevant rule files, adding comments where a security decision deserves one.
3. Security review. Claude checks the produced code against each applicable rule's checklist and surfaces what was applied.

---

Rule inventory (v1.3.1)

The plugin bundles 23 core security rules in two tiers.

Always-apply rules (3)

Checked on every code operation:

Rule	Purpose
codeguard-1-hardcoded-credentials	Prevent secrets, passwords, API keys, and tokens in source code
codeguard-1-crypto-algorithms	Ban weak algorithms (MD5, SHA-1, DES) and require modern alternatives
codeguard-1-digital-certificates	Validate certificate expiration, key strength, and signature algorithms

Each rule file ships its own detailed guidance, checklists, and examples; Claude pulls them in on demand rather than loading the full set every turn.

---

Usage examples

Database access

# Claude applies codeguard-0-input-validation-injection.
def get_user(email):
    query = "SELECT * FROM users WHERE email = ?"
    return cursor.execute(query, (email,))

API keys

// Claude applies codeguard-1-hardcoded-credentials.
const apiKey = process.env.STRIPE_API_KEY;
if (!apiKey) {
  throw new Error("STRIPE_API_KEY not configured");
}

Password hashing

# Claude applies codeguard-1-crypto-algorithms Argon2 instead of MD5/SHA-1.
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)

File upload validation

// Claude applies codeguard-0-file-handling-and-uploads.
const multer = require("multer");
const upload = multer({
  limits: { fileSize: 5 * 1024 * 1024 }, // 5MB cap
  fileFilter: (req, file, cb) => {
    if (file.mimetype.startsWith("image/")) cb(null, true);
    else cb(new Error("Only images allowed"));
  },
});

Asking for a focused review

Review this authentication code against codeguard-0-authentication-mfa
and codeguard-0-session-management-and-cookies. Call out anything that
doesn't follow the checklists.

Designing with security in mind

I'm about to add a file-upload endpoint. Walk me through what
codeguard-0-file-handling-and-uploads requires before I start.

---

Team deployment

To install CodeGuard automatically for everyone who opens a project, add it to the project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "project-codeguard": {
      "source": {
        "source": "github",
        "repo": "cosai-oasis/project-codeguard"
      }
    }
  },
  "enabledPlugins": {
    "codeguard-security@project-codeguard": true
  }
}

When team members trust the repository folder, Claude Code prompts them to install the marketplace and enable the plugin. See Plugin settings for the full schema.

For enterprise environments, administrators can lock down which marketplaces are installable via the strictKnownMarketplaces managed setting, see managed marketplace restrictions.

---

Updates

CodeGuard ships periodic rule updates. Claude Code can pick these up automatically.

Enable auto-update for the marketplace (one time):

1. Run /plugin
2. Switch to the Marketplaces tab
3. Select project-codeguard
4. Choose Enable auto-update

With auto-update enabled, Claude Code refreshes the marketplace at startup and bumps installed plugins to the latest version, prompting you to run /reload-plugins if anything changed.

Manual refresh:

/plugin marketplace update project-codeguard
/reload-plugins

To disable Claude Code's auto-updater while still receiving plugin updates, set both DISABLE_AUTOUPDATER=1 and FORCE_AUTOUPDATE_PLUGINS=1 in your shell environment.

---

Managing the plugin

Open the manager: /plugin four tabs cycle with Tab (or Shift+Tab):

• Discover, browse plugins from all your marketplaces
• Installed, view, enable, disable, or uninstall your plugins
• Marketplaces, add, remove, or update marketplace sources
• Errors, surfaces any plugin-loading failures

Direct commands:

/plugin disable codeguard-security@project-codeguard
/plugin enable codeguard-security@project-codeguard
/plugin uninstall codeguard-security@project-codeguard

After any of these, run /reload-plugins to apply the change without restarting.

---

Troubleshooting

/plugin not recognized. Your Claude Code is older than 1.0.33. Update it (see Prerequisites), then restart your terminal.

Plugin not showing up. Run /plugin, check the Installed tab, and confirm codeguard-security@project-codeguard is present and enabled. If not, reinstall:

/plugin install codeguard-security@project-codeguard
/reload-plugins

Plugin loaded but rules aren't being applied. Two common causes:

1. The task doesn't match any context-specific rule's scope. Try a more security-relevant prompt, or explicitly cite a rule (e.g., "review against codeguard-0-input-validation-injection").
2. The skill cache is stale. Clear it and reinstall:

   rm -rf ~/.claude/plugins/cache
   

   then restart Claude Code and reinstall the plugin.

Marketplace not loading. Verify the repository is reachable and that .claude-plugin/marketplace.json exists at the path. Re-run /plugin marketplace add cosai-oasis/project-codeguard.

Errors tab shows entries. Open /plugin → Errors and follow the messages. The most common cause is a Claude Code version that pre-dates a skill feature; update first.

For deeper debugging, see Anthropic's plugin troubleshooting guide.

---

Building from source

Contributors and forks can rebuild the plugin locally:

cd /path/to/project-codeguard
uv run python src/convert_to_ide_formats.py

This regenerates:

• skills/software-security/, the Claude Code plugin (always uses core rules only)
• dist/, bundles for every supported IDE/agent (Cursor, Windsurf, Copilot, Codex, Antigravity, OpenCode, OpenClaw, Hermes, Claude Code)

To build IDE bundles that include OWASP supplementary rules:

uv run python src/convert_to_ide_formats.py --source core owasp

The supplementary set only affects dist/, not skills/.

---

Plugin architecture

project-codeguard/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest (version, skills paths)
│   └── marketplace.json         # Marketplace catalog
│
├── sources/                     # Authored inputs (version controlled)
│   ├── rules/
│   │   ├── core/                # 23 core security rules + template
│   │   └── owasp/               # OWASP supplementary rules
│   ├── skills/                  # Authored skills (security-review, etc.)
│   ├── agents/                  # Subagent definitions
│   └── templates/               # Rule template
│
├── skills/                      # Generated... do not edit
│   └── software-security/
│       ├── SKILL.md             # Activation rules + language→rule table
│       └── rules/               # Generated rule files
│
├── dist/                        # Release artifacts (not in git)
│   ├── .claude/                 # Claude Code bundle
│   ├── .cursor/                 # Cursor IDE format
│   ├── .windsurf/               # Windsurf IDE format
│   ├── .github/                 # Copilot format
│   ├── .agents/                 # Antigravity + Codex shared dir
│   ├── .opencode/               # OpenCode bundle
│   ├── .openclaw/               # OpenClaw bundle
│   └── .hermes/                 # Hermes bundle
│
└── src/                         # Conversion + validation tooling
    ├── convert_to_ide_formats.py
    ├── emit_agents.py
    └── artifact_targets.py

How Claude consumes the bundle

1. Reads SKILL.md, pulls in the activation criteria and the language→rules mapping table.
2. Initial check, identifies whether credentials, the current language, and the task domain trigger specific rules.
3. Applies rules, references the relevant files under rules/ for secure-by-default patterns and checklists.
4. Generates code, produces output that satisfies the always-apply rules and the contextually relevant ones.
5. Explains, surfaces which rules were applied and why.

---

Resources

• Project website: https://project-codeguard.org
• GitHub: https://github.com/cosai-oasis/project-codeguard
• Getting started: https://project-codeguard.org/getting-started/
• Issues: https://github.com/cosai-oasis/project-codeguard/issues
• Discussions: https://github.com/cosai-oasis/project-codeguard/discussions
• Claude Code plugin docs: https://code.claude.com/docs/en/discover-plugins
• Claude Code skills docs: https://code.claude.com/docs/en/skills

---

License

• Rules Creative Commons Attribution 4.0 International (CC BY 4.0)
• Tools Apache License 2.0

[billbrietstout]

Updated page addresses:

1. "Restart Claude Code (if prompted)" outdated. Current command is /reload-plugins
2. "The skill is automatically loaded" incomplete; requires /reload-plugins per current docs
3. /plugin update codeguard-security@project-codeguard this command doesn't exist in current Claude Code. Updates happen via auto-update or /plugin marketplace update
4. /plugin list doesn't exist as a CLI command. The interactive /plugin UI has an "Installed" tab; CLI verification uses claude plugin install ... --scope ... style or just /plugin
5. "/plugin → 'Manage Plugins'" wrong UI label. Current tabs are: Discover, Installed, Marketplaces, Errors
6. marketplaces array in .claude/settings.json wrong key. Current key is extraKnownMarketplaces (object, not array), with a source object inside
7. "23 security rule files" vs "22 comprehensive security rules" vs "3 + 19 = 22" inconsistent and wrong. Reality: 3 always-apply + 20 context-specific = 23 rules
8. Missing rule: codeguard-0-mcp-security is in the repo but missing from the table
9. Version History "Version 1.0.0 / 1.0.1" current version is 1.3.1 per pyproject.toml, plugin.json, and latest release
10. /plugin doesn't have a "Manage Plugins" submenu, that label is from a different/older UI

Inaccurate against current Claude Code docs

1. "Restart Claude Code (if prompted)" current flow is /reload-plugins. No restart needed.
2. /plugin update @ this command doesn't exist. Updates happen via auto-update toggle or /plugin marketplace update followed by /reload-plugins.
3. /plugin list, also doesn't exist. Verification is via /plugin → Installed tab.
4. "/plugin → 'Manage Plugins'" wrong UI label. The current UI has four tabs: Discover, Installed, Marketplaces, Errors.
5. .claude/settings.json schema, the page used a marketplaces array with source-as-string and a plugins array. The actual schema is extraKnownMarketplaces (object, keyed by marketplace name) with a structured source object, plus enabledPlugins (object keyed by plugin@marketplace).
6. No mention of the Claude Code 1.0.33+ version requirement for /plugin to exist.

Inaccurate against the repo itself

1. Rule counts contradicted themselves, the page said "23 security rule files," then "22 comprehensive security rules," then listed "3 always-apply + 19 context-specific = 22." Reality from the repo: 3 always-apply + 20 context-specific = 23 rules.
2. Missing rule: codeguard-0-mcp-security exists in sources/rules/core/ but isn't in the page's table.
3. Version History stuck at 1.0.0/1.0.1, pyproject.toml, plugin.json, and the latest release all say 1.3.1.

Other improvements

1. Added a "Trust note", Anthropic's docs are explicit that plugins execute arbitrary code with user privileges, and a security project's docs should say so.
2. Added the strictKnownMarketplaces pointer for enterprise hardening.
3. Reframed troubleshooting around the actual current flow (~/.claude/plugins/cache, the Errors tab).
4. Cut the "Version History" section since it was both outdated and not particularly useful in a how-to page, a CHANGELOG.md or GitHub Releases serves that purpose better.
5. Removed the "Build the Plugin" section's claim that "skills/ always contains 23 core security rules", kept the substance but rephrased since the count was being repeated inconsistently across the page.

[thomas-bartlett]

#75 covered the concrete rule-count cleanup from this issue: the docs now consistently use 23 rules and include codeguard-0-mcp-security.

Leaving this open for now so the remaining Claude Code plugin docs review is not lost. The still-useful items here are the install/update flow, current plugin UI labels, settings schema, trust/strictKnownMarketplaces guidance, troubleshooting notes, and whether the old version-history/build wording should be revised or removed.