news

Build in public: keeping the OSK v4 AI Assistant robust at 250+ skills

Sebastien Dubois

06 May 2026 — 2 min read

Canonical version: Build in public: keeping the OSK v4 AI Assistant robust at 250+ skills.

Build-in-public update on the AI Assistant Architecture inside OSK v4.

In OSK v4, I built these mechanisms in from the start instead of adding them at the end. The system now has more than 250 skills, and it's steadier than it was at 50.

Here are the eight mechanisms:

Capability indirection. Every skill declares metadata.capability: <domain>.<subject>.<verb>. Cross-skill references go through capabilities, never names. Renaming a skill doesn't break the skills that refer to it. It's dependency inversion applied to skills.
Runtime path resolution, no hardcoding. This was today's biggest refactor. About 120 skills used to embed their own copy of "where does the daily note live" logic. Now they declare metadata.note-types and resolve folders, templates and prefixes from osk-cli at run time, using one canonical Setup block. A skill can no longer point to a stale folder path.
Spec-layered frontmatter, validator-enforced. osk-meta-skill-health went from 10 checks to 18 yesterday. New ones include spec-layering-top-level, capability-collision (one capability equals one skill, hard error), workflow-without-composes, and claude-code-field-nested. The validator now checks the frontmatter contract automatically.
Dispatcher consolidation. The moment a second skill would share (subject, verb) with an existing one, I refactor into a polymorphic skill with a --mode flag. osk-action-archive absorbed four siblings this way. That's the single responsibility principle (SRP) applied per capability.
Self-updating capability registry. The AI Assistant Capabilities note runs Dataview Serializer plugin for Obsidian queries that read SKILL.md frontmatter directly. There's nothing to regenerate, so the receptionist's routing table always matches the skills that actually exist.
Catalog visibility hygiene. Claude Code packs every visible skill's description into an 8000-char budget. Context loaders, *-shared and *-barrel skills MUST set disable-model-invocation: true. This keeps routing precise as the number of skills grows.
Progressive disclosure. Skills don't preload. Frontmatter is always visible; bodies only load when a skill actually fires. The receptionist routes from 250+ frontmatter blocks, then pulls one SKILL.md into context on demand. This is the Prompt Lazy Loading AI Design Pattern (PLL). The token cost stays flat as skills are added.
Call-chain safety. Max depth 3, no duplicates, no cycles, chain context mandatory. These hard limits prevent "A calls B calls A" loops between agents.

If you're building anything with more than ten AI skills, look at capability indirection and runtime path resolution first. The other six mechanisms build on them.