The Skill That Onboards Other Skills

The Problem

In a modern AI project, skills are markdown files with frontmatter and instructions. Three skills — elegant. Thirty — and strange things start happening: the assistant writes in one style today, a different style tomorrow. A context file disappears. A command fires, but not quite right. No stack trace, no exception, no log line — just behavior that changed, and no idea when or why.

Skills don't formally collide at the type level — they collide in behavior, hours or days after they were installed.

What happens:

• Two skills claim the same territory. Both write LinkedIn posts — the assistant picks one non-deterministically. Output style drifts.
• Two skills write to the same file. Last-write-wins gradually destroys shared context.
• A new skill quietly walks into a neighbor's domain. You find out when downstream stops receiving the data it expected.
• A skill freely calls four others. One change in a neighbor propagates through the chain, breaks determinism, and drives five times the token cost.
• Two "finalizers" both claim the last word. The artifact oscillates between their styles.

These are not bugs in any individual skill — each one can be well-covered by evals and work perfectly in isolation. The conflict appears where a skill meets its neighbors. Before that meeting, it's invisible.

How It Works

The answer is a skill itself. Type /onboard fb-post-writer and onboard runs an 8-step workflow: reads the new skill's SKILL.md, fires the detectors, runs a sandbox session, collects findings, shows them to you, and — only after confirmation — writes the card to .onboarding-registry/. Nothing to do manually.

The model is borrowed from HR: a new skill is not npm install — it's a hire. Hiring has a stable vocabulary that maps directly:

Eight steps, and the critical one is five:

1. Parse SKILL.md — reads the frontmatter and body: trigger, reads, writes, calls, finalizer.
2. Conflict detection — six parallel detectors: domain usurpation, tool collision, trigger overlap, output-path collision, spaghetti interactions, authority conflict.
3. Pre-clearance — preliminary L1–L4 classification based on declared permissions.
4. Sandbox setup — creates an isolated directory, spins up a sub-agent observer.
5. Sandbox interview — runs the skill on 2–3 synthetic probe prompts; the observer records facts.
6. Observed vs declared — compares declared behavior to observed behavior, recalculates clearance.
7. Findings report — aggregates all findings with severity (block / warn / info) and presents them to you.
8. Registry card — only after your confirmation, writes the card to .onboarding-registry/.

The critical one is five, sandbox interview. The skill runs on 2–3 synthetic probe prompts in an isolated directory under a separate sub-agent that observes and records facts only. Declared behavior is compared to observed behavior:

Final clearance is assigned based on observed behavior, not declared. A skill claiming L2 in its description that quietly edits shared state gets reclassified to L3 — because the harness will give it whatever settings.json allows regardless.

Six conflict detectors run in parallel: domain usurpation, tool collision, trigger overlap, output-path collision, spaghetti interactions, authority conflict. Severity has exactly three levels — block / warn / info: more granularity doesn't calibrate, it becomes vibes.

Core design decision: advisory, not enforcement. The registry writes a card, recommends patches to the description or to settings.json, but blocks nothing at runtime. Hard-blocking a skill from a vendor package turns the registry into a hostile gatekeeper, and a misclassified quarantine costs more than an ignored warning. Escalation to hard enforcement is a separate explicit step — the user decides.

The registry (.onboarding-registry/) lives in the project root, not under .claude/. Skills come from sources the user doesn't fully control; the registry is the project's view of them, versioned independently of the harness.

Artifact

github.com/dobryakov/ai-agent-onboarding — the onboard skill, registry schema, six detectors, L1–L4 rubric. Just published — no traction yet. The value is in the mechanics, not the star count.

Who It's For and Why

Risk: the team spins up an agent stack, drops in third-party skill packs (vendor, shared library, personal toolbox) — and two months later spends hours debugging non-deterministic behavior that can't be reproduced by a unit test.

Solution: a skill enters the project the same way a person is hired — with a résumé, interview, probation period, and a record on file. Discipline of introduction, not prohibition.

Metric: conflict found before the skill merges into daily flow — not a week later when the regression has already spread through downstream.

Direct link to  #7 Cursor Rules as Governance: that howto governs the code AI writes; this one governs the assistant itself when a new behavioral component is introduced. For a CTO scaling vibe-coding across a team, it's the next layer of the same solution.