Reserved Handle Policy
Use this skill to protect a public handle namespace without turning a broad list into an unexplained permanent ban.
Start with the policy model
Separate two kinds of restriction:
hard_reserved: platform routes, authority terms, security identities, and service names that users must never claim.
manual_claim_required: scarce or impersonation-prone names that an administrator may assign after identity review.
Do not report both as merely taken. A caller needs to distinguish an existing account, a permanent platform reservation, and a claim that can be reviewed.
Read rationale.md before changing the tiers or source cohorts. Load reserved-handles.toml only when implementing, auditing, or inspecting the concrete list; it is intentionally kept out of the default context because it contains thousands of names.
Implementation workflow
- Locate the canonical handle validator, signup command, rename command, availability endpoint, database uniqueness constraints, and administrator mutation boundary.
- Preserve the product's existing normalization rules. Compare a normalized lowercase handle and a separator-stripped skeleton where separators are allowed.
- Apply the stricter result in this order:
- hard-reserved exact or confusable match;
- an already-issued current or historical handle;
- three-or-fewer-character skeleton;
- manual-claim exact or confusable match;
- otherwise available.
- Reject protected names in open signup and self-service rename. Do not add a role-based bypass to those public commands.
- If manual assignment is in scope, create a distinct administrator command with claimant evidence, reason, actor, timestamp, and audit record. A bootstrap-admin claim may be a narrowly documented exception.
- Keep historical handles permanently unavailable if old profile or content URLs redirect through handle history.
- Return an explicit machine-readable reason such as
manual_claim_required and give the user honest UI copy.
- Add focused tests for hard reservations, short handles, separators, one example from every cohort, existing/historical handles, bootstrap behavior, and audited assignment.
Using the bundled registry
Run the classifier against one or more candidates:
python3 reserved-handle-policy/scripts/check_handle.py admin swyx a_i available-name
Validate the registry after editing it:
python3 reserved-handle-policy/scripts/validate.py
The TOML resource is the source of truth. It uses one compact inline table per handle while retaining ranks, karma, source spelling, cohort metadata, and policy rules. The CSV is a flattened convenience export containing one row per exact handle and all matching cohorts. The bundled readers require Python 3.11 or newer for the standard-library tomllib parser and install no dependencies.
Refreshing cohorts
Read refresh.md for the source-specific retrieval notes and the exact Hacker News query.
- Treat rankings as dated evidence, not timeless identity truth.
- Preserve source order and rank metadata when available.
- Filter candidates through the product's syntactic handle rules, but record how many source rows were excluded.
- Do not import a raw Reddit karma leaderboard as authoritative. There is no official global ranking, and third-party lists are noisy with bots, repost accounts, deleted users, and unsafe identities. Keep Reddit curated unless a better defensible dataset appears.
- Adding a newly protected name cannot reclaim a handle already issued. Produce a collision report before changing a live policy.
- Keep source URLs, capture date, cohort rationale, and policy version beside the data.
Handoff
Report:
- counts by tier and cohort;
- normalization and confusable rules;
- collisions with existing or historical accounts;
- which user-facing and administrator flows changed;
- tests run;
- source capture dates and any cohorts deliberately excluded.
1---2name: reserved-handle-policy3description: Design, implement, audit, or refresh protected username and handle namespaces for public products. Use whenever a product has open signup, mutable handles, profile URLs, impersonation or squatting risk, reserved route names, short usernames, common-word or common-name claims, developer/AI terminology, notable social identities, or administrator-approved handle assignment—even if the user only asks for a username denylist.4metadata:5 source: https://skillmd.com/skills/swyxio/reserved-handle-policy6---78# Reserved Handle Policy910Use this skill to protect a public handle namespace without turning a broad list into an unexplained permanent ban.1112## Start with the policy model1314Separate two kinds of restriction:15161. `hard_reserved`: platform routes, authority terms, security identities, and service names that users must never claim.172. `manual_claim_required`: scarce or impersonation-prone names that an administrator may assign after identity review.1819Do not report both as merely `taken`. A caller needs to distinguish an existing account, a permanent platform reservation, and a claim that can be reviewed.2021Read [rationale.md](references/rationale.md) before changing the tiers or source cohorts. Load [reserved-handles.toml](references/reserved-handles.toml) only when implementing, auditing, or inspecting the concrete list; it is intentionally kept out of the default context because it contains thousands of names.2223## Implementation workflow24251. Locate the canonical handle validator, signup command, rename command, availability endpoint, database uniqueness constraints, and administrator mutation boundary.262. Preserve the product's existing normalization rules. Compare a normalized lowercase handle and a separator-stripped skeleton where separators are allowed.273. Apply the stricter result in this order:28 - hard-reserved exact or confusable match;29 - an already-issued current or historical handle;30 - three-or-fewer-character skeleton;31 - manual-claim exact or confusable match;32 - otherwise available.334. Reject protected names in open signup and self-service rename. Do not add a role-based bypass to those public commands.345. If manual assignment is in scope, create a distinct administrator command with claimant evidence, reason, actor, timestamp, and audit record. A bootstrap-admin claim may be a narrowly documented exception.356. Keep historical handles permanently unavailable if old profile or content URLs redirect through handle history.367. Return an explicit machine-readable reason such as `manual_claim_required` and give the user honest UI copy.378. Add focused tests for hard reservations, short handles, separators, one example from every cohort, existing/historical handles, bootstrap behavior, and audited assignment.3839## Using the bundled registry4041Run the classifier against one or more candidates:4243```bash44python3 reserved-handle-policy/scripts/check_handle.py admin swyx a_i available-name45```4647Validate the registry after editing it:4849```bash50python3 reserved-handle-policy/scripts/validate.py51```5253The TOML resource is the source of truth. It uses one compact inline table per handle while retaining ranks, karma, source spelling, cohort metadata, and policy rules. The CSV is a flattened convenience export containing one row per exact handle and all matching cohorts. The bundled readers require Python 3.11 or newer for the standard-library `tomllib` parser and install no dependencies.5455## Refreshing cohorts5657Read [refresh.md](references/refresh.md) for the source-specific retrieval notes and the exact Hacker News query.5859- Treat rankings as dated evidence, not timeless identity truth.60- Preserve source order and rank metadata when available.61- Filter candidates through the product's syntactic handle rules, but record how many source rows were excluded.62- Do not import a raw Reddit karma leaderboard as authoritative. There is no official global ranking, and third-party lists are noisy with bots, repost accounts, deleted users, and unsafe identities. Keep Reddit curated unless a better defensible dataset appears.63- Adding a newly protected name cannot reclaim a handle already issued. Produce a collision report before changing a live policy.64- Keep source URLs, capture date, cohort rationale, and policy version beside the data.6566## Handoff6768Report:6970- counts by tier and cohort;71- normalization and confusable rules;72- collisions with existing or historical accounts;73- which user-facing and administrator flows changed;74- tests run;75- source capture dates and any cohorts deliberately excluded.