Agent Skills in HSM-II

HSM-II treats company_skills as the canonical Company OS skill contract. On-disk SKILL.md folders remain supported for portability and progressive disclosure, including Agent Skills and Hermes-style packs, but imported Markdown is an input format rather than the live governance standard.

Canonical Company OS skills should carry metadata, permissions, required tools, expected artifacts, eval fixtures, governance class, provenance, and promotion evidence. See docs/company-os/HSM_NATIVE_SPINE.md for the native-spine contract.

What HSM-II Does

• Scans <HSMII_HOME>/skills and HSM_SKILL_EXTERNAL_DIRS for **/SKILL.md.
• Stores catalog metadata for progressive disclosure; full SKILL.md body is loaded via skill_md_read or /skill <slug>.
• Loads extra files under the skill folder with skill_resource_read using relative paths only; .. paths are rejected.
• skills_list returns skill_id from YAML name, skill_dir, and optional license, compatibility, metadata, and allowed_tools when present.
• Validation warns by default for mismatched name vs folder name, invalid name syntax, or missing description when Agent Skills front matter is used. Set HSM_AGENT_SKILLS_STRICT=1 to exclude those entries from the catalog.
• Validated skills can be imported or promoted into company_skills; once promoted, Company OS governance and eval evidence are authoritative.

Canonical Source Precedence

The first configured root wins when more than one SKILL.md has the same runtime slug. scripts/company-os-up.sh orders repository roots as skills/, .agents/skills/, then .claude/skills/; <HSMII_HOME>/skills still precedes all external roots. Mirrors are allowed only when byte-identical. Run node scripts/check-skill-catalog.mjs before changing a portable pack; CI rejects divergent duplicate runtime slugs and declared names.

Upstream Tooling

To validate portable packs against the Agent Skills reference rules, use the skills-ref CLI from agentskills/skills-ref when installed:

skills-ref validate ./my-skill

Seeds In This Repo

See templates/hsmii/skills/ for a compliant example where the name front matter matches the folder name in lowercase kebab-case.

Why Descriptions Matter

Models map user intent to tool names, descriptions, schemas, and skill catalog blurbs the same way they would pick a function. Unclear text leads to skipped skills, wrong tools, or overuse of generic primitives.

For a concise, model-centric explanation of tool calls, Hermes-style function calling, progressive disclosure, pitfalls, context economics, and batching tool turns, load skills/llm-tool-skill-reasoning/SKILL.md.