Because copying markdown into a folder is not installing a package. It is a hire: a new slice of behavior enters the assistant and will collide with its neighbors tomorrow. A skill here is an instruction pack for an AI assistant (Claude Code / Cursor): frontmatter, rules, declared reads/writes/calls. While the intake path is empty, every new file under .claude/skills/ is a silent hire with no interview and no record in the file.
I'm building onboarding for skills. "Grigory, are you serious? Just copy the skill into the project folder."
Not quite.
Three skills — elegant. Thirty — behavior starts drifting. The assistant writes in a different style today than yesterday. A command fires but does the wrong thing. A shared context file disappears. No stack trace, no exception, no log line. Just different behavior, and nobody can say which commit flipped it.
Skills do not collide at the type level. They collide in behavior — hours or days after installation. Before they meet their neighbors, the conflict is invisible: each skill can be covered by evals and work flawlessly in isolation. That is why "just copy it" sounds reasonable — and why it breaks later.
Why this is a real problem
The pattern repeats:
- Two skills both claim "I write LinkedIn posts." The assistant picks one nondeterministically. Style drifts across publications.
- Two skills write to the same shared state file. Last-write-wins quietly destroys accumulated context.
- A new skill steps into a neighbor's domain. You find out when downstream stops getting what it expects.
- One skill calls four others freely. One edit propagates through the chain, burns 5× the tokens, and breaks determinism.
- Two "finalizers" both claim the last word. The artifact oscillates between their styles.
These are not bugs in individual skills. The conflict happens where the skill meets its neighbors. Merging a third-party skill pack like npm install is hiring someone with no interview — and you pay for it not at merge time, but a week later, when the regression is already in daily flow.
The metric that makes the hassle worth it: a conflict caught before the skill becomes part of how the team works.
What that looks like in practice
I built a skill that onboards other skills — ai-agent-onboarding. Not because "process says so," but because otherwise there is no moment where declared behavior is checked against observed behavior before the skill sits next to its neighbors.
You type /onboard fb-post-writer. The onboard skill reads SKILL.md, runs detectors, puts the candidate through a sandbox, collects findings, shows them to you, and only after confirmation writes a card into .onboarding-registry/.
The model is borrowed from HR for a reason. Hiring already has language for what skills still lack:
| Hiring | Skill onboarding |
|---|---|
| Résumé | SKILL.md + frontmatter |
| Interview | Sandbox run on probe prompts |
| Security clearance | Levels L1–L4 |
| Probation | First N calls under closer watch |
| Reporting line | Domain finalizer |
| Exit interview | Archive record with removal reason |
The point of the sandbox interview: clearance is assigned by what the skill actually does, not by what it claims. A skill that advertises L2 but edits shared state is reclassified to L3 — because the harness will give it whatever settings.json already allows. Without that step you trust the résumé. With it you watch what the hire actually does on probation.
In parallel, six conflict detectors (domain usurpation, tool collision, trigger overlap, output-path collision, spaghetti interactions, authority conflict) answer another why: where exactly the new skill will cross the ones already living in the project. Severity has three levels only — block / warn / info. More levels stop being a scale and become vibes.
And one why in the other direction: the registry is advisory, not enforcement. It writes a card and recommends patches, but it does not block runtime. Hard-quarantining a vendor skill costs more than an ignored warning. Onboarding exists so the decision is conscious — not so automation forbids the team from working.
The registry lives at .onboarding-registry/ in the project root, not under .claude/: skills arrive from places the team does not control; the project's opinion about them is versioned separately from the harness.
Full methodology, tables, failure modes: Skill onboarding governance howto.
Where the motive fails
- Advisory does not block. A team can ignore the report and get the same conflict. There is no protection against indifference — that is a conscious choice for reversibility.
- Detectors produce false positives on legitimate domain overlap (two writer skills for different platforms).
policies.mdhelps, but it is manual work. - Lazy intake. Skills installed before
onboardexisted land in the registry aslazy_intake: true— incomplete data, no sandbox interview. Without an explicit re-onboarding they stay half-blind. - Sandbox ≠ production. A skill that needs a live MCP to a private service degrades to a "paper interview." Honest fallback; weaker findings.
- L4 without a reviewer. The "modifies the harness" level escalates severity, but if nobody owns those changes, escalation becomes noise.
Onboarding only pays off where the team will look at findings. If markdown still gets dropped into the folder with a shrug, process will not save you.
Who this "why" is for
CTOs, Heads of AI, tech leads, and architects scaling vibe-coding across a team and already pulling in third-party skill packs — vendor, shared library, personal toolbox. The question is not how to make a pretty registry. The question is why you let new assistant behavior land with no interview when human hiring already has a process.
The neighboring layer is rules for the code the model writes: Cursor rules as governance. That howto covers standards on model output. This one covers why intake discipline for a new component of the assistant's own behavior is worth having. You usually need both.
Bottom line
A skill enters the project the way a person is hired: résumé, interview, probation, a record in the file. Not a discipline of prohibition — a discipline of introduction. Onboarding is not there because "enterprise says so." It is there because without it you have no moment when the conflict is still visible — before it becomes "behavior just changed."
Repo: github.com/dobryakov/ai-agent-onboarding
Howto: dobryakov.net/howto/skill-onboarding-governance.html
Related: book-as-context for subject-matter grounding, and agent security when a system prompt is not enough.