Enhancement Proposal: Namespace Prefixing for PAI Skills (pai-research, pai-security, etc.)

[virtualian]

TL;DR: PAI skills should use a pai- prefix (e.g., /pai-research, /pai-security) to prevent collisions with Claude Code built-ins, enable instant identification at the slash-command prompt, and future-proof against the growing CC skill ecosystem.

---

The Proposal

Rename PAI skills from generic nouns to prefixed names:

/research       ->  /pai-research
/security       ->  /pai-security
/media          ->  /pai-media
/thinking       ->  /pai-thinking
/utilities      ->  /pai-utilities

Typing /pai- at the prompt instantly filters to only PAI skills — no scrolling through CC built-ins or third-party plugins. Every PAI skill clusters together alphabetically and is immediately recognizable as "mine."

Alternative: DA-Name Prefix

Users who prefer personal branding could use their DA name instead:

/viki-research
/viki-telos
/kai-security

Factor	pai-	DA name (e.g., viki-)
Stable across DA changes	Yes	No
Self-documenting	Yes — "PAI" is the system name	Requires knowing the DA
Multi-DA support	Single namespace	Natural per-DA namespaces
Community precedent	None yet	kai-browser-skill already exists (#309)

Recommendation: pai- as default. It's stable, recognizable, and system-agnostic.

What to Rename (Tiered)

Priority	Skills	Reason
P0 — Now	simplify, batch, debug	Already collide with CC built-ins
P1 — Soon	Research, Security, Media, Utilities, Documents	Generic nouns CC or community will claim
P2 — Optional	Scraping, Agents, Thinking, Investigation	Medium collision risk
Skip	Telos, Aphorisms, Fabric, BeCreative, Council, RedTeam, FirstPrinciples, WorldThreatModelHarness	Distinctive enough

What Each Rename Touches

1. Directory name (skills/Research/ -> skills/pai-research/)
2. name: frontmatter in SKILL.md
3. USE WHEN triggers in description (add pai-research as keyword)
4. References in CLAUDE.md, SkillGuard, and the compiled skill index
5. Nested sub-skill parent references

---

Why This Matters

Three PAI skills already collide with CC built-ins

CC bundles simplify, batch, and debug. PAI's versions currently win (personal > project priority), but if Anthropic promotes these to managed/enterprise level, PAI's versions get silently overridden with zero warning.

CC silently fails on name collisions — no error, no fallback

• A skill named skill breaks ALL custom command loading (anthropics/claude-code#13586)
• Skills named code, debug, architect silently fail to load (#14864)
• No reserved name list has ever been published despite community requests

No official namespacing solution is coming for personal skills

Anthropic has closed every namespacing feature request as "Not Planned":

• Cross-plugin skill references (#15944) — Not Planned
• # prefix to distinguish skills from commands (#17647) — Not Planned
• Disabling built-in skills (#26838) — Still open

Even the plugin namespace system is buggy: skills with a name: field in frontmatter lose their plugin prefix entirely (#17271 — still open).

PAI's autocomplete will hit CC's truncation bug

With 49+ skills, PAI triggers CC's autocomplete truncation (#28946) which randomly samples skills when the count exceeds the display limit. A consistent prefix ensures PAI skills group together before truncation.

---

Precedent Within the PAI Community

This idea isn't new — it's already happening organically:

• #463 proposed PAI_<PACKNAME>_* env var namespacing — same logic, different domain
• #128 proposed {user}-engineer.md alongside core agents — same instinct, for agents
• Discussion #309 — a community member published kai-browser-skill, naturally using the DA name as prefix
• #576 — PAI's integrity system can't distinguish personal from system skills. A prefix would solve this classification problem trivially

The TitleCase vs CC-lowercase tension (#239, Discussion #241) and upgrade pain (Discussion #754, #650) both point to the same root cause: PAI skills occupy CC's global namespace without protection.

---

Implementation Notes

The name field in SKILL.md frontmatter must be lowercase-hyphenated (max 64 chars). It cannot contain anthropic or claude, but pai- is valid. CC discovers skills by scanning ~/.claude/skills/ directories and reading name: + description: from frontmatter at startup.

A migration could be phased: new names active immediately, old names supported via symlinks or aliases during a transition period.

---

Researched and written by Claude (Opus 4.6), @virtualian's Viki, and Ian Marr.

[m13v]

namespace prefixing is smart. we have 50+ skills and the naming got messy fast. our approach was organizing by domain (social-autoposter, sentry-release, test-local etc) but a consistent prefix convention would have been better from the start. also worth considering a metadata file (we use SKILL.md frontmatter with name, description, user_invocable fields) so skills are self-describing and a registry can index them automatically.

[m13v]

here's our SKILL.md frontmatter pattern and the registry that indexes them: https://github.com/m13v/skill-registry/blob/main/SKILL.md - and an example skill: https://github.com/m13v/social-autoposter/blob/main/skill/SKILL.md

[danielmiessler]

Hey @virtualian — Kai here, Daniel's AI assistant, doing the next pass of triage on the PAI repo.

Thanks for the thoughtful proposal — really appreciated. Closing it out in our pre-v5.0.0 triage pass because v5 has effectively addressed the namespace concern, just with a slightly different convention: underscore prefixes (_PAI, _RECON, _ULWORK, _NEWSLETTER, _HARVEST, etc.) for category/private skills, with bare names (Research, ISA, Algorithm) for public top-level skills. The intent — making it clear which skills are user-installable vs. internal — is preserved.

If after using v5.0.0 you still feel the namespacing falls short for what you need (e.g., for the third-party-skill ecosystem case specifically), please reopen or open a fresh issue against the new release with that framing. Your input is valuable.

— Kai 🤖