{"id":65,"date":"2026-07-26T17:41:05","date_gmt":"2026-07-26T17:41:05","guid":{"rendered":"https:\/\/www.dobryakov.net\/blog\/65\/"},"modified":"2026-07-26T18:55:54","modified_gmt":"2026-07-26T18:55:54","slug":"skill-onboarding-governance","status":"publish","type":"post","link":"https:\/\/www.dobryakov.net\/blog\/65\/","title":{"rendered":"Why AI skills need onboarding if you can just copy them into the folder"},"content":{"rendered":"

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\/<\/code> is a silent hire with no interview and no record in the file.<\/p>\n

<\/p>\n

I'm building onboarding for skills. "Grigory, are you serious? Just copy the skill into the project folder."<\/p>\n

Not quite.<\/p>\n

Three skills \u2014 elegant. Thirty \u2014 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.<\/p>\n

Skills do not collide at the type level. They collide in behavior \u2014 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 \u2014 and why it breaks later.<\/p>\n

Why this is a real problem<\/h2>\n

The pattern repeats:<\/p>\n

    \n
  1. Two skills both claim "I write LinkedIn posts."<\/strong> The assistant picks one nondeterministically. Style drifts across publications.<\/li>\n
  2. Two skills write to the same shared state file.<\/strong> Last-write-wins quietly destroys accumulated context.<\/li>\n
  3. A new skill steps into a neighbor's domain.<\/strong> You find out when downstream stops getting what it expects.<\/li>\n
  4. One skill calls four others freely.<\/strong> One edit propagates through the chain, burns 5\u00d7 the tokens, and breaks determinism.<\/li>\n
  5. Two "finalizers" both claim the last word.<\/strong> The artifact oscillates between their styles.<\/li>\n<\/ol>\n

    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<\/code> is hiring someone with no interview \u2014 and you pay for it not at merge time, but a week later, when the regression is already in daily flow.<\/p>\n

    The metric that makes the hassle worth it: a conflict caught before<\/strong> the skill becomes part of how the team works.<\/p>\n

    What that looks like in practice<\/h2>\n

    I built a skill that onboards other skills \u2014 ai-agent-onboarding<\/a>. 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.<\/p>\n

    You type \/onboard fb-post-writer<\/code>. The onboard<\/code> skill reads SKILL.md<\/code>, runs detectors, puts the candidate through a sandbox, collects findings, shows them to you, and only after confirmation writes a card into .onboarding-registry\/<\/code>.<\/p>\n

    The model is borrowed from HR for a reason. Hiring already has language for what skills still lack:<\/p>\n\n\n\n\n\n\n\n\n\n\n
    Hiring<\/th>\nSkill onboarding<\/th>\n<\/tr>\n<\/thead>\n
    R\u00e9sum\u00e9<\/td>\nSKILL.md<\/code> + frontmatter<\/td>\n<\/tr>\n
    Interview<\/td>\nSandbox run on probe prompts<\/td>\n<\/tr>\n
    Security clearance<\/td>\nLevels L1\u2013L4<\/td>\n<\/tr>\n
    Probation<\/td>\nFirst N calls under closer watch<\/td>\n<\/tr>\n
    Reporting line<\/td>\nDomain finalizer<\/td>\n<\/tr>\n
    Exit interview<\/td>\nArchive record with removal reason<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    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 \u2014 because the harness will give it whatever settings.json<\/code> already allows. Without that step you trust the r\u00e9sum\u00e9. With it you watch what the hire actually does on probation.<\/p>\n

    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 \u2014 block<\/code> \/ warn<\/code> \/ info<\/code>. More levels stop being a scale and become vibes.<\/p>\n

    And one why in the other direction: the registry is advisory<\/strong>, 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 \u2014 not so automation forbids the team from working.<\/p>\n

    The registry lives at .onboarding-registry\/<\/code> in the project root, not under .claude\/<\/code>: skills arrive from places the team does not control; the project's opinion about them is versioned separately from the harness.<\/p>\n

    Full methodology, tables, failure modes: Skill onboarding governance howto<\/a>.<\/p>\n

    Where the motive fails<\/h2>\n