Skill

Skills come from two roots: <workspace>/.agents/skills, which people manage with skill_add and skill_remove, and a bundled root at /workspace/skills (overridden by BLUECLAW_BUNDLED_SKILLS_PATH) that cannot be written or shadowed. The frontmatter keys read are name, description, metadata.kim.intern.tool-references, kim.intern.requires-environment and kim.intern.requires-any-file. allowed-tools is ignored: tool descriptors own policy, and only tool-references makes a skill depend on tools. The text <skill> in a body is replaced with the skill's install directory.

A skill whose required environment variables, tools or files are missing is set aside and logged as skill.environment.missing, skill.tools.missing or skill.file.missing.

Progressive disclosure

The prompt carries a compact index of candidate skills, retrieved by BM25 and cached at .blueclaw/skill-index.json. The full SKILL.md body is injected only for skills selected for the turn whose tools are callable, at most five. The selection is recorded in agent.instructions_loaded with each skill's decision and reason and each source's path, size and SHA-256.

Every SKILL.md body a turn selects is charged on every step of that turn. Keep a normal skill under 8 KB and a complex artifact skill under 12 KB, and put long references, scripts and assets in references/, scripts/ and assets/ beside it to be read or run when the task needs them. blueclaw does not enforce a size limit on these files.