Public Export Sanitization

Sanitizing Internal Content Before It Goes Public

When moving content from a private or internal source into a public destination (a public repo, a blog post, a conference talk, a shareable draft), the expensive failure is a silent context leak: an internal cloud project id, a service-account email, an internal hostname, a personal name, or a Markdown link that points back into a private repo. A human reviewer reliably misses one class of these every time, and the miss becomes visible only after it is public.

The judgment (what to keep, how to reword) is yours. The detection is a script: run it, don't re-derive it.

When to Use This Skill

The tripwire: run it on every export

bash "${CLAUDE_SKILL_DIR}/scripts/check-public-export.sh" --patterns <org.patterns> <export-tree>

It scans for internal identifiers and for Markdown links that escape the export or are broken. Exit 1 means findings to review; exit 2 is a usage error. Patterns ignore <placeholder> tokens, so a genericized tree comes back clean. Dot-directories such as .claude/ and .github/ are scanned too; only .git/ is skipped.

Built-in patterns are org-neutral only: GCP service-account emails (*.iam.gserviceaccount.com), 12-digit GCP project numbers, and absolute home paths. Your organisation's identifier shapes go in a --patterns file, one label::regex per line (extended regex, # comments allowed), kept wherever your private config lives rather than in the public tree:

# org.patterns
GCP project id (acme-*)::\bacme-[a-z][a-z0-9-]{2,}\b
Internal hostname (corp.example)::\b[a-z0-9-]+\.corp\.example\b
Staff email::\b[a-z0-9._%+-]+@example\.com\b

Without a --patterns file the scan checks only the built-in shapes, so a clean result then says nothing about org-specific identifiers.

Two modes:

• Pre-export gate (default, strict): scan the export set on its own; any link leaving it is flagged. This is the self-containment gate below.
• Post-placement verify: once the content sits inside a larger public repo, pass --repo-root <repo> so links to public siblings (../LICENSE, ../other-doc) are allowed and only repo-escaping or broken links flag.

Other options: --names <file> (personal names, which can't be regex'd; seed the list from the source's git authors and access grants; one literal entry per line; only a bare # or # followed by whitespace is a comment line, and a trailing whitespace-#-whitespace tail such as Alice Smith # author is a trailing comment, so #1234 still flags that PR or issue number), --allow <regex> (dismiss a known-benign hit, such as a CSS class that shares a project-id prefix; check the regex does not also hide real ids), --no-links, -q.

It takes one tree per run. Given several paths it scans only the last, and the summary line then reads like a clean sweep of all of them. Loop over the trees instead, and check that each summary names the tree you meant.

No pattern catches private repository names, and they are often the leak that matters most: a repo name is not shaped like an identifier, so no regex can recognise it. Grep for them separately, with the list taken from GitHub rather than from memory:

gh repo list <owner> --visibility private --limit 1000 --json name --jq '.[].name' > /tmp/private-repos.txt
grep -rnoFf /tmp/private-repos.txt <export-tree>

Short repo names match as substrings (a repo named dot matches "two-dot diff"), so read each hit rather than counting them.

It is not a secret scanner. Run gitleaks for tokens and keys; this catches context leakage, a different axis.

Curation rubric (per candidate doc or file)

Keep a candidate only if it clears all five:

Genericization checklist (identifier to placeholder)

Replace the real value and keep the architecture. Common classes:

• Cloud project id / number: <gcp-project-id> / <project-number>
• Service-account email: <sa-name> (or <sa-name>@<gcp-project-id>.iam.gserviceaccount.com; the bare form keeps the scan clean and consistent)
• Database, KMS, and secret-manager resource names: <cloud-sql-instance>, <…-keyring>, <…-secret>
• Internal hostnames: <…-host>
• Private repo names: describe the shape instead ("a 16-file PR", "a node-pack repo"). A public repo in the same org can be named; check its visibility rather than assuming it from the org
• Internal issue/PR refs (#NNNN): drop, or "(tracked internally)"
• Personal names and usernames: a role ("a team member", "an applicant")
• Internal cost or accounting codes: the project name, not the numeric code

Keep the non-sensitive facts that carry the value: region, machine types, CIDRs, component/chart/image versions, public DNS hostnames, public upstream URLs.

A claim about how the organisation is configured ("this org's main has no required status checks") needs more than a placeholder: it is internal, and it goes stale when the setting changes. Replace it with the check the reader can run on their own repo. For that example: mergeStateStatus is UNSTABLE when a failing check is present but not required, and BLOCKED when it is required and the merge is refused.

Link rewriting

No link may leave the export set except to public upstream. Links into the private source (../adr/…, ../../infra/…, .claude/rules/…) become self-contained prose or are repointed within the export. The script's link check is the backstop for the class humans miss most.

Delivery discipline

• Branch off a fresh origin/main, stage only the new paths (git add <paths>, never -A), and check that git log origin/main..HEAD shows only your commit before pushing.
• If the export PR is squash-merged and you pushed more commits to its branch afterward, those commits are in neither main nor the squash. Replay them onto a fresh origin/main in a new PR.
• Run the tripwire once more against the content in its destination (--repo-root <repo>) before opening the PR.

Agentic Optimizations