Agent skill packaging — SKILL.md contract, lazy references, zero-dep tools

frameworkactive owner: philip · updated 2026-11-14

relates: yaml-dsl-form-runtime

Agent skill packaging — SKILL.md contract, lazy references, zero-dep tools

Reusable agent capabilities ship as skills: a SKILL.md (name + trigger-rich description + body under 500 lines) with optional references/ (loaded on demand), scripts/ (zero-dependency CLIs), and assets/ (templates). Install to .agents/skills/ — the cross-agent standard.

Problem it solves

• Prompts in chat don't persist or compose; giant instruction files blow context and trigger wrong skills. Skills make capabilities discoverable (description matching), portable (one folder), and testable (evals).

Shape

• SKILL.md frontmatter: name (matches dir, lowercase-hyphen) + description (1–500 chars: what it does, when to use it, trigger phrases, boundaries). Body: task steps, style rules, checklists.
• references/ — deep material loaded only when needed (keeps SKILL.md lean).
• scripts/ — zero-dependency Node/Python CLIs with --help/--dry-run and contract tests (node --test with mocked fetch, no live calls).
• assets/ — templates and fixtures the skill instantiates.
• Versioning is dual-layer: repo release version (plugin.json/marketplace.json/VERSIONS.md) + per-skill metadata.version; CI enforces both (scripts/check-versions.mjs).
• Trigger evals: evals/triggers/*.json prompt sets run before shipping description changes (trigger-eval.mjs).

Rules

• Description carries the trigger load: concrete nouns, trigger phrases, scope boundaries, related skills — under 500 chars (Claude Code caps listings ~30k chars total).
• SKILL.md under 500 lines; move depth to references/.
• Tools are zero-dependency and dry-runnable; tests mock external calls.
• Any shipped change bumps per-skill version in the same PR; repo version bumps on skill additions/structure changes.
• Skills compose via the delivery chain (## Chain footer data contract in ai-framework).

Anti-patterns

• Description stuffed with synonyms (dilutes trigger matching).
• SKILL.md as a manual — depth belongs in references/.
• Tools requiring credentials or network for their own tests.
• Version bumps forgotten (invisible updates) or over-bumped (noise).

Sources

• marketingskills/AGENTS.md (spec, versioning, CLI rules, writing style)
• marketingskills/tools/clis/ (67 zero-dep tools), tools/REGISTRY.md
• marketingskills/skills/*/evals/triggers/ + scripts/trigger-eval.mjs
• factory/ai-framework (delivery chain, skills consumed by agents)