The Agent Skills specification defines the runtime contract well: what agents load, how directories are structured, what frontmatter means. It intentionally does not prescribe how authors organize source files. That gap is fine — until teams maintain skill libraries at scale.
skills-house is a reference implementation for authoring conventions. These are constructive proposals — not criticisms — informed by building a real build pipeline.
1. Separate authoring from distribution
Proposal: Document that the spec describes dist layout, and encourage optional authoring layouts with a build step in between.
Authors need modular source. Agents need flat, predictable dist. Conflating the two forces either bloated SKILL.md files or hand-maintained duplicates.
2. Standardize frontmatter validation rules
Proposal: Clarify that name must match the containing directory name
(lowercase, hyphen-separated). skills-house enforces this at build time; agents should expect consistency.
3. Description as activation trigger
Proposal: Add guidance that description must state both what
the skill does and when to load it. Routers and humans use this field to decide activation.
Vague descriptions are a top cause of missed skill loads.
4. Cross-skill dependency notation
Proposal: Define a standard agent-facing note when skill A depends on skill B — install command, package name, optional version. skills-house injects:
Depends on:
my-skill
If not available, suggest:npx skills add my-skill
Standardizing this note format helps agents handle missing dependencies uniformly.
5. Progressive disclosure patterns
Proposal: Recommend keeping SKILL.md under a context budget (~150–200 lines expanded)
and moving deep reference material to references/. The spec supports this; v2 could
include examples.
6. Script safety guidelines
Proposal: Add non-normative security guidance for scripts/ —
no credential embedding, scope destructive operations, prefer explicit user approval for installs.
Reference implementation
skills-house specs document these conventions in detail:
I'd welcome discussion in Agent Skills community channels. The goal is interoperability — authors should write once and ship to any agent.