New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Standard for agent plugins that keeps user-specific content in a private overlay outside the public plugin.

version
1.0.0
GitHub stars
32
View on GitHub

What it does

  • Adds audit-plugins, check-guidance, and setup skills for auditing and maintaining plugin marketplaces
  • Audits for leaked personal particulars or secrets, storage rules, overlay conformance, skill limits, and version drift
  • Enforces storing user data in an overlay folder outside ~/.claude and secrets only as environment variable names
  • Designed for plugin authors who need one public generic plugin serving both themselves and other users

The Public Plugin, Private Overlay standard for agent plugins, aligned with Anthropic's plugin and skill guidance: one public generic plugin, the user's own content in a consistent overlay folder outside ~/.claude, caches in CLAUDE_PLUGIN_DATA, secrets in sensitive userConfig. audit-plugins audits a publisher's marketplaces and plugins against it (leaks of personal particulars or secrets, storage rules, overlay conformance, skill limits, version drift) and brings them into line in approved batches. check-guidance re-reads the Anthropic docs the standard quotes and proposes updates when they change.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install public-private-overlay@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Audit plugins and bring them into line

This is a large job: a publisher can have hundreds of plugins. Work in two phases. Audit is read-only and done in one pass. Align runs in batches, each one approved by the user before anything changes. The source of truth is this repository: AGENTS.md, docs/checklist.md and docs/anthropic-alignment.md. Read those three before aligning anything.

1. Load your settings

Find the data folder: $PPO_HOME, $CLAUDE_USER_DATA/public-private-overlay/, then ~/.claude-user-data/public-private-overlay/. Read profile.env (PPO_MARKETPLACES, PPO_REPOS_ROOT, PPO_PERSONAL_TERMS) and audit-plugins.md if they exist. They win over the defaults below. With no profile, ask for the marketplace files and the repos root, and offer setup at the end. Without a personal-terms list, the leak check only finds secrets, so say so.

2. Audit (read-only)

Pull the marketplace clones first (git -C <clone> pull) so the audit reads what is published. Then:

A="${CLAUDE_PLUGIN_ROOT}/scripts/audit-plugins.py"
python3 "$A" $(for m in $PPO_MARKETPLACES; do printf -- '--marketplace %s ' "$m"; done) \
  --repos-root "$PPO_REPOS_ROOT" --personal-terms "$PPO_PERSONAL_TERMS" > "<data folder>/audits/<date>.json"
  • --visibility asks GitHub whether each repo is really public (one API call per plugin, so check the rate limit first). Without it, visibility is inferred from the marketplace name ("private" in the name means private).
  • --only a,b audits named plugins. --plugin <dir> --assume-public audits a single checkout.
  • Small first: run it on three plugins you know, read the findings, then run everything.

Each plugin gets a class:

ClassMeaningPriority
leakpublic, with a personal term or a secret value1. Fix now
fixerrors or warnings: storage, settings load step, limits, drift2
candidate-publicprivate, with no personal terms found3. Offer to convert
conformingnothing above info levelnone
not-found-locallylisted, but no clone under the repos rootClone it or skip it, and say which

The rules, and what each one means:

RuleSeverityFix
secret-valueerrorA token or op:// reference. In a public plugin, treat it as exposed: tell the user to rotate it (their call), replace it with an environment variable name, and check git history (publishing-private-repo)
personal-termerror if publicMove the particular to the overlay (profile.env or <skill>.md) and write the generic text
author-linkinfoThe term appears only inside a URL (author or repo link). Fine
writes-plugin-rooterrorWrite to ${CLAUDE_PLUGIN_DATA} (caches) or the overlay (user content)
touches-dot-claudewarnReview it: reads of Claude Code's own files are fine, writes are not
legacy-locationwarn, or info when documented as a migrationMove to the overlay and offer migration
hardcoded-home-pathwarnUse ~, $HOME or a profile key
user-content-in-plugin-datawarnUser content belongs in the overlay
no-load-step, no-setup-skill, resolver-incompletewarnAdd the standard load step, a setup skill, and the full resolution order
no-data-storage-sectioninfoAdd ## Data storage
skill-too-long, skill-name-invalid, skill-description-*warn or errorAnthropic's limits: 500 lines; name of 64 or fewer lowercase-hyphen characters without "claude" or "anthropic"; description of 1,024 or fewer characters
version-drift, name-mismatch, listed-twicewarnMake plugin.json and the entry agree. Each plugin is listed in one marketplace
parallel-private-plugininfoFold the private twin's particulars into the public plugin's overlay

Path rules (touches-dot-claude, legacy-location, hardcoded-home-path, user-content-in-plugin-data) are warnings in code and info in markdown, because prose often describes a path rather than using it. A plugin can list vendored or quoted material in .audit-ignore at its root, one glob per line (for example sources/**).

The script uses heuristics. Before a finding goes into a batch, open the line. A personal term in an example, or a ~/.claude path that is only read, is not a bug.

3. Report

Write <data folder>/audits/<date>.md: the totals by class and by rule, then one row per plugin that isn't conforming (class, top rules, counts). Show the user the totals, every leak by name, and the proposed batches. Keep personal terms out of anything public: the report stays in the private data folder.

4. Align, one batch at a time

Propose batches of 5 to 10 plugins, in priority order: leaks, then storage errors, then overlay conformance, then limits and drift, then candidate-public conversions. For each batch, say what will change in each plugin and wait for a yes. Then, per plugin:

  1. Pull. Fix by following AGENTS.md: particulars to the user's overlay (write them there in the same pass, so the user's next run behaves as before), generic text in the plugin, the load step, ## Data storage, setup, caches to ${CLAUDE_PLUGIN_DATA}.
  2. Re-run the audit on just this plugin (--only <name>) until it is conforming, or until every remaining finding is reviewed and recorded as acceptable in audit-plugins.md.
  3. Bump the version in plugin.json and the marketplace entry. Commit only the paths you changed, then push.
  4. A leak whose history holds the particular: a public repository keeps serving old commits by SHA. Ask whether to recreate the repository (docs/converting-a-private-plugin.md). Never rewrite history without a yes.
  5. Candidate-public conversions follow docs/converting-a-private-plugin.md in full, including the owner's yes before anything is published.

After each batch, push the marketplace changes, refresh whatever indexes the marketplace (if there is a catalogue, sync it), and report the batch: which plugins went from which class to which, plus anything skipped and why.

5. Close out

Re-run the full audit. Report the before and after totals. Keep both JSON files in audits/. Record any accepted exceptions (rule, plugin, file, reason) in audit-plugins.md so the next audit can skip them.

Data storage

Reads profile.env, personal-terms.txt and audit-plugins.md. Writes audits/<date>.json and audits/<date>.md in the data folder. During alignment, it also writes to the plugins being fixed and to the user's overlays for those plugins.

Readme

Public Plugin, Private Overlay

A standard for agent plugins (Claude Code plugins and skills, and similar systems) that have to work for one specific person without being written for only that person.

Ship one public, generic plugin. Keep everything about the user in a private data folder outside it: the overlay. The plugin reads the overlay every time it runs, so the same published plugin serves its author and a stranger, and a plugin update never touches anyone's settings.

Three rules follow from that:

  1. Never a parallel private fork. A private copy of a public plugin drifts on the first fix and is never reconciled. Put the differences in the overlay instead.
  2. A private companion plugin only as a last resort, when one of the tests below is met.
  3. Secrets by environment variable name only. The plugin says which variable it needs. The user's own secrets route fills it. The plugin never stores a value and never says where the user keeps them.

Author: Daniel Rosehill.

Built on Anthropic's guidance

Claude Code gives a plugin three official places to keep things: the plugin itself (${CLAUDE_PLUGIN_ROOT}, replaced on every update), a data directory for caches and generated files (${CLAUDE_PLUGIN_DATA}, deleted on uninstall), and userConfig values the user enters when installing (secrets go to secure storage). This standard uses each of them for what Anthropic intends, and adds one thing they don't cover: a consistent folder outside ~/.claude for what the user writes, which survives uninstall and can live in the user's own private repository. Details and sources: docs/anthropic-alignment.md.

Use it as a plugin

This repository is also an installable plugin, public-private-overlay:

SkillDoes
audit-pluginsAudits every plugin across your marketplaces against this standard and Anthropic's guidance (leaked particulars and secrets, storage, overlay conformance, skill limits, version drift), then fixes them in batches you approve
check-guidanceMaintainers: re-reads the Anthropic docs quoted in sources/anthropic/, reports what changed, and updates the standard to match
setupYour marketplaces, repos root and a private list of personal terms

sources/anthropic/ holds verbatim extracts of the Anthropic documentation this standard relies on, with the date fetched, so every rule can be traced to its source and drift can be detected.

Private only when

Make a plugin, or a skill, private only if one of these holds:

  • Nothing useful is left once the user's particulars are taken out.
  • The workflow's existence is itself sensitive, or it belongs to a client or employer.
  • The owner has a standing rule that covers it.

Otherwise it is public, and the particulars go to the overlay.

Sort every particular

List what in the workflow is specific to the user, and give each item a home.

ParticularHome
Values: hosts, IDs, emails, paths, account namesprofile.env in the overlay
SecretsNeither. The skill names the environment variable; the user's secrets route fills it
Formats: templates, presets, voices, layoutsOverlay files, named like the built-ins
Procedure: "in my setup, always do X first"<skill-name>.md in the overlay, the skill's private notes
Records: logs, history, stateThe plugin's workspace repository, private

If the generic skill still does something useful after that, it is public.

The three parts

Each part runs on a different clock.

PartWhat it isLifecyclePrivacy
PluginSkills, agents, commands, MCP declarations, built-in templatesReplaced wholesale on updatePublic
OverlayA data folder outside the plugin: profile.env, per-skill notes, templates/Survives every plugin updatePrivate, one per user per plugin
WorkspaceA private repository made from a public template repository, holding one project's working stateCreated once per project, then divergesPrivate, one per project

Most plugins need the plugin and the overlay. The workspace is for plugins that do sustained work on something, not ones that answer a question and exit.

Which clock does it run on

Almost every "where does this file go" question is answered by that:

  • Thrown away and replaced when the plugin updates? Plugin.
  • True about the user rather than the project, and you would be unhappy to publish it? Overlay.
  • The thing being worked on, and you would want its history? Workspace.

Put a file on the wrong clock and the failure is predictable:

MistakeWhat happens
User settings inside the plugin directorySilently wiped by the next update
User particulars in the plugin repositoryPublished to everyone who installs it
A private fork to hold the particularsDrifts from the public plugin and misses every fix
Working data in the plugin repositoryPublished, and mixed into every user's install
User preferences in the template repositoryCopied into everyone's workspace as defaults
Secret values anywhereCommitted, eventually

The overlay

<data folder>/
  profile.env        KEY=value. Comments are instructions for this user
  <skill-name>.md    Private notes for one skill. They win over the skill's defaults
  templates/         Same names as the plugin's built-ins. The user's copy wins

Find the data folder in this order, and stop at the first match:

  1. $<PLUGIN>_HOME
  2. $CLAUDE_USER_DATA/<plugin>/
  3. ~/.claude-user-data/<plugin>/, if ~/.claude-user-data exists
  4. ${XDG_DATA_HOME:-~/.local/share}/claude-plugins/<plugin>/, if that root exists
  5. ~/.claude-user-data/<plugin>/ (the default; the setup skill creates it)

Never the plugin install directory, and never the agent's own config directory. Full detail: docs/overlay.md.

What the plugin ships

  1. A setup skill that writes profile.env, asking only for what it cannot detect.

  2. A load step at the top of each skill, which can be copied as is:

    ## 1. Load your settings
    
    Find the data folder: `$<PLUGIN>_HOME`, `$CLAUDE_USER_DATA/<plugin>/`, then
    `~/.claude-user-data/<plugin>/`. Read `profile.env` and `<skill-name>.md` if they
    exist. They win over the defaults below. If there is no profile, use the defaults
    and offer `setup` at the end.
    
  3. Overlay-first lookup for formats: the user's file by name, then the built-in. Built-ins are read from the plugin, not copied out, so they keep getting fixes.

  4. A ## Data storage section in each skill, saying what it reads and writes in the overlay.

  5. Defaults that work with no overlay, since a stranger has none.

A new format is data, not a skill. One generic skill serves every template, and the template's own fields hold what is particular to it.

The workspace

For plugins that accumulate work, the third part is a private repository made from a public template repository:

gh repo create <name> --template <owner>/<template> --private --clone

This gives four things at once:

  1. The folder structure is defined in one public, reviewable place.
  2. The workspace starts private and stays private. It is a fresh repository with no upstream link, so nothing in it flows back.
  3. History is evidence. Where the order of operations is the guarantee, a commit timestamp proves it.
  4. The workspace carries its own instructions. If the template includes the skills, the repository is runnable by any agent with the plugin uninstalled.

The overlay can name a different template (<PLUGIN>_TEMPLATE in profile.env), so a user's fork of the template wins over the author's.

Use a workspace when at least two of these hold:

  • The work accumulates across sessions and the user comes back to it.
  • There is state the user would want to read, correct, diff or keep.
  • The output should stay usable if the plugin is uninstalled or replaced.
  • The order in which things happened needs to be provable.

Superseded: ~/.claude-plugins/<name>/

An earlier version of this standard (August 2026, then called Plugin-Workspace-Vault) kept user settings in a "vault" at ~/.claude-plugins/<name>/config.yaml with a credentials.yaml of secret pointers. That location is superseded by the overlay resolution order above. To migrate, move the folder's contents to the overlay folder, turn config.yaml keys into profile.env lines, and replace credential pointers with the environment variable names the skills read. A plugin may report the old location and offer to move it. It should not keep reading from it.

Read next

DocumentCovers
docs/anthropic-alignment.mdWhat Anthropic's docs provide and how the standard maps onto them
AGENTS.mdDirectives for an agent building, converting or auditing a plugin
docs/overlay.mdThe data folder: resolution, contents, load step, secrets, merge rules
docs/converting-a-private-plugin.mdTurning an existing private plugin into a public one plus an overlay
docs/anatomy.mdWhat belongs in each part, file by file, with the awkward cases
docs/variables.mdHow the plugin finds its own files, the overlay and the workspace
docs/sync.mdKeeping a vendored copy of a template in step, and detecting drift
docs/worked-example.mdReal plugins built this way
docs/checklist.mdShip checklist
reference/A resolver script, a sync script and skill templates to copy

Licence

MIT. See LICENSE.

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Public-Plugin-Private-Overlay
Author
Daniel Rosehill
Category
Repo Scaffolding & Retrofitting
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to public-private-overlay

More AI Agents & Orchestration