Skills

A skill is an asset with a SKILL.md. How it is plugged as instructions, what claude loads, why codex and grok refuse it, why skills grant no tools, how suggestions work and what is not built

Skills as assets

A skill is an asset whose folder has a SKILL.md at its top with YAML frontmatter holding a non-empty name (lowercase letters, digits, hyphens) and description. Such an asset has kind skill. It is added by any normal add path (adopt a folder, drop a zip, add files to a new asset) and removed by retiring it. Versions, the profile, search and "used in" are the asset's own.

01Plugging#

A skill is plugged into a run's nodes with the instructions role (the third role beside reference and target).

• Only an asset of kind skill with a valid SKILL.md at the version go would freeze can be plugged as instructions.
• go freezes the skill at that version. If the skill moved since the card was previewed, the card is stale. The launch record and the asset's "used in" list name the skill with role instructions and that version, so retiring the skill later changes neither.
• An instructions plug adds no context declaration: the skill is never handed over as reference data. A skill plugged as reference is just data.
• The claude runtime gets exactly the plugged skills, at their frozen versions, as a per-attempt session plugin (.claude-plugin/plugin.json and skills/<name>/) passed with --plugin-dir and removed after the attempt. Nothing under ~/.claude/skills is referenced. The init check still fails closed: the skills it reports must equal the plugged names and the only plugin must be that per-attempt one.

02Decisions#

• Runtimes without skill support (codex, grok) refuse an instructions plug on that node. The SKILL.md is not inlined as labelled text. That keeps instructions meaning real skill loading, and keeps a skill from being smuggled into a prompt as if it were data. A card with a skill on such a node is refused when it is previewed.
• Packs. There is no pack format in the code. A pack's craft may name skill assets by id instead of inlining craft text. Each named skill is plugged as instructions and frozen like any other plug.
• Skills and packs never grant tools. They describe tools and declare intent. A tool is granted only by the node's profile and capabilities, which plugging a skill does not change. The one tool a skill adds is the Skill tool a model loads it with.

03Suggestions#

At draft, a skill whose description (or name) matches the ticket text is suggested with role instructions, on the claude reading nodes only. Keeping the suggestion plugs it with that role. Nothing is plugged until the user keeps it.

04Not built here#

Plugging skills into the conductor (global or per project, in settings) is not done: the conductor is not started through the claude runtime adapter, and settings has no plug model. It needs its own ticket.