
public-private-overlay
Standard for agent plugins that keeps user-specific content in a private overlay outside the public plugin.
- version
- 1.0.0
- GitHub stars
- 32
What it does
- Adds
audit-plugins,check-guidance, andsetupskills 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
~/.claudeand 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-PluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install public-private-overlay@danielrosehillRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceAudit 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"
--visibilityasks 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,baudits named plugins.--plugin <dir> --assume-publicaudits a single checkout.- Small first: run it on three plugins you know, read the findings, then run everything.
Each plugin gets a class:
| Class | Meaning | Priority |
|---|---|---|
leak | public, with a personal term or a secret value | 1. Fix now |
fix | errors or warnings: storage, settings load step, limits, drift | 2 |
candidate-public | private, with no personal terms found | 3. Offer to convert |
conforming | nothing above info level | none |
not-found-locally | listed, but no clone under the repos root | Clone it or skip it, and say which |
The rules, and what each one means:
| Rule | Severity | Fix |
|---|---|---|
secret-value | error | A 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-term | error if public | Move the particular to the overlay (profile.env or <skill>.md) and write the generic text |
author-link | info | The term appears only inside a URL (author or repo link). Fine |
writes-plugin-root | error | Write to ${CLAUDE_PLUGIN_DATA} (caches) or the overlay (user content) |
touches-dot-claude | warn | Review it: reads of Claude Code's own files are fine, writes are not |
legacy-location | warn, or info when documented as a migration | Move to the overlay and offer migration |
hardcoded-home-path | warn | Use ~, $HOME or a profile key |
user-content-in-plugin-data | warn | User content belongs in the overlay |
no-load-step, no-setup-skill, resolver-incomplete | warn | Add the standard load step, a setup skill, and the full resolution order |
no-data-storage-section | info | Add ## Data storage |
skill-too-long, skill-name-invalid, skill-description-* | warn or error | Anthropic'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-twice | warn | Make plugin.json and the entry agree. Each plugin is listed in one marketplace |
parallel-private-plugin | info | Fold 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:
- 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}. - Re-run the audit on just this plugin (
--only <name>) until it isconforming, or until every remaining finding is reviewed and recorded as acceptable inaudit-plugins.md. - Bump the version in
plugin.jsonand the marketplace entry. Commit only the paths you changed, then push. - 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.
- 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:
- 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.
- A private companion plugin only as a last resort, when one of the tests below is met.
- 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:
| Skill | Does |
|---|---|
audit-plugins | Audits 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-guidance | Maintainers: re-reads the Anthropic docs quoted in sources/anthropic/, reports what changed, and updates the standard to match |
setup | Your 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.
| Particular | Home |
|---|---|
| Values: hosts, IDs, emails, paths, account names | profile.env in the overlay |
| Secrets | Neither. The skill names the environment variable; the user's secrets route fills it |
| Formats: templates, presets, voices, layouts | Overlay 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, state | The 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.
| Part | What it is | Lifecycle | Privacy |
|---|---|---|---|
| Plugin | Skills, agents, commands, MCP declarations, built-in templates | Replaced wholesale on update | Public |
| Overlay | A data folder outside the plugin: profile.env, per-skill notes, templates/ | Survives every plugin update | Private, one per user per plugin |
| Workspace | A private repository made from a public template repository, holding one project's working state | Created once per project, then diverges | Private, 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:
| Mistake | What happens |
|---|---|
| User settings inside the plugin directory | Silently wiped by the next update |
| User particulars in the plugin repository | Published to everyone who installs it |
| A private fork to hold the particulars | Drifts from the public plugin and misses every fix |
| Working data in the plugin repository | Published, and mixed into every user's install |
| User preferences in the template repository | Copied into everyone's workspace as defaults |
| Secret values anywhere | Committed, 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:
$<PLUGIN>_HOME$CLAUDE_USER_DATA/<plugin>/~/.claude-user-data/<plugin>/, if~/.claude-user-dataexists${XDG_DATA_HOME:-~/.local/share}/claude-plugins/<plugin>/, if that root exists~/.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
-
A
setupskill that writesprofile.env, asking only for what it cannot detect. -
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. -
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.
-
A
## Data storagesection in each skill, saying what it reads and writes in the overlay. -
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:
- The folder structure is defined in one public, reviewable place.
- The workspace starts private and stays private. It is a fresh repository with no upstream link, so nothing in it flows back.
- History is evidence. Where the order of operations is the guarantee, a commit timestamp proves it.
- 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
| Document | Covers |
|---|---|
| docs/anthropic-alignment.md | What Anthropic's docs provide and how the standard maps onto them |
| AGENTS.md | Directives for an agent building, converting or auditing a plugin |
| docs/overlay.md | The data folder: resolution, contents, load step, secrets, merge rules |
| docs/converting-a-private-plugin.md | Turning an existing private plugin into a public one plus an overlay |
| docs/anatomy.md | What belongs in each part, file by file, with the awkward cases |
| docs/variables.md | How the plugin finds its own files, the overlay and the workspace |
| docs/sync.md | Keeping a vendored copy of a template in step, and detecting drift |
| docs/worked-example.md | Real plugins built this way |
| docs/checklist.md | Ship 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- qa-teamv1.0.0
- rclone-managerv0.1.0
- remote-video-editingv1.4.1
- repo-retrofitterv1.0.0
- repo-to-contentv1.1.4
- report-analystv0.1.0
- research-spacev1.4.1
- resource-list-builderv0.2.0
- resume-typesetterv1.1.1
- rtl-emailv0.2.0
- rtl-skillsv1.5.0
- rudderv2.9.4
- schedule-managerv1.0.1
- screenshottingv2.1.0
- security-auditorv1.0.0
- security-checkupv1.0.0
- seov1.0.0
- session-hopperv1.1.0
- session-restorev0.2.1
- shoppingv2.2.0
- site-skill-builderv1.2.0
- skill-geniev0.5.0
- skill-or-notv0.1.1
- skill-thisv0.7.0
Similar to public-private-overlay
More AI Agents & Orchestration
eccaffaan-m/everything-claude-code308.6K starsHarness-native ECC operator layer - 72 agents, 328 skills, 99 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready work
mattpocock-skillsmattpocock/skills304.3K starsMatt Pocock's agent skills for real engineering (grilling, spec/ticket flows, TDD, code review, domain modelling and more).
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
agent-skillsaddyosmani/agent-skills119.6K starsProduction-grade engineering skills covering every phase of software development: spec, plan, build, verify, review, and ship.
agentdbruvnet/ruflo82.2K starsAgentDB (external: maintained in ruvnet/agentdb, pinned to commit 27678c3, plugin 3.6.0): agentdb's own standalone MCP server pinned to agentdb@3.6.0 (vector me
last30daysmvanhorn/last30days-skill72.2K starsResearch any topic across Reddit, X, YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, and 5+ more sources. AI agent scores by upvotes, likes, and re