Skill System Foundry

A meta-skill for constructing and evolving AI-agnostic skill systems.

This skill governs the creation and maintenance of a two-layer architecture: skills (with optional capabilities) and roles. All skills produced by this system follow the Agent Skills specification. They incorporate authoring best practices from official vendor guides. Role contracts align with tool integration guidance for seamless deployment across platforms.

Important: Capabilities are optional, granular sub-skills within a parent skill. Do not create capabilities by default. Only introduce them when the integrator explicitly asks for them or when the domain clearly demands decomposition (3+ distinct operations with different trigger contexts). Start with a standalone skill; evolve to router+capabilities only when justified.

Architecture Overview

The skill system follows a strict two-layer architecture — skills and roles. Dependencies flow strictly downward — never the reverse. A capability must never know it's being orchestrated. A role references skills but never other roles.

The dependency direction governs references between layers, not where orchestration begins. Two valid orchestration paths exist:

Path 1:  orchestration skill → roles → skills (with optional capabilities)
Path 2:  skill (standalone or router) → role(s) → skill's capabilities

• Path 1 — Coordination-only skill. A lean standalone skill sequences roles across domains. Contains no domain logic.
• Path 2 — Self-contained skill. A domain skill loads one or more roles for interactive workflow logic. The skill owns capabilities; roles provide responsibility, authority, and constraints, plus handoff rules, sequencing, and interaction patterns.

See references/architecture-patterns.md for decision checklists and constraints per path.

Each layer has a clear responsibility:

• Skills — Canonical, AI-agnostic knowledge and logic. Conform to the Agent Skills specification. A skill handles a task directly (standalone) or optionally routes to capabilities for complex domains that warrant decomposition.
• Roles — Canonical, AI-agnostic orchestration contracts. A role defines responsibility, authority, and constraints, plus handoff rules and workflow sequencing while composing multiple skills/capabilities.

Bundled Resources

references/ — Read when you need guidance

• references/authoring-principles.md — Shared skill authoring principles (cross-platform consensus)
• references/architecture-patterns.md — Standalone vs router decisions and architecture patterns
• references/tool-integration.md — Tool-specific paths, discovery, and deployment
• references/agentskills-spec.md — Agent Skills specification compliance guide
• references/claude-code-extensions.md — Claude Code-specific frontmatter and features
• references/codex-extensions.md — Codex agents/openai.yaml and discovery hierarchy
• references/cursor-extensions.md — Cursor cross-vendor discovery and rules migration
• references/anti-patterns.md — Common mistakes and how to avoid them
• references/directory-structure.md — Full directory layout and conventions
• references/workflows.md — Step-by-step workflows for creation, migration, deployment, and auditing

assets/ — Copy and fill in when creating components

• assets/skill-standalone.md — Template for standalone skills
• assets/skill-router.md — Template for router skills with capabilities
• assets/capability.md — Template for capabilities under a router
• assets/role.md — Template for roles
• assets/manifest.yaml — Manifest schema template

scripts/ — Run for validation and auditing

• scripts/audit_skill_system.py — Audit skill system structure and consistency
• scripts/validate_skill.py — Validate a single skill against the spec
• scripts/scaffold.py — Scaffold new skills or roles from templates
• scripts/bundle.py — Bundle a skill into a self-contained zip bundle for distribution
• scripts/lib/validation.py — Shared name validation logic
• scripts/lib/references.py — Reference scanning, resolution, and graph traversal
• scripts/lib/constants.py — Centralized constants and configuration

Core Principles

1. Agent Skills Specification Compliance

All skills must conform to the Agent Skills specification (agentskills.io). Every registered skill directory contains a SKILL.md with valid YAML frontmatter. The name field matches the parent directory name, lowercase + hyphens only, max 64 chars. The description field is max 1024 chars and describes both what the skill does and when to trigger it. Third-person voice is a foundry convention, not a spec requirement.

Note: capabilities are discovery-internal sub-skills. Their entry point is capability.md. Capability frontmatter is optional (use it when portability/promotion to standalone is likely).

Progressive disclosure is respected at all levels:

• Level 1: Metadata (~100 tokens) — name + description, always in context
• Level 2: Instructions (<5000 tokens / recommended max 500 lines) — loaded when triggered
• Level 3: Resources (unlimited) — scripts, references, assets, on demand

2. Token Economy

Discovery tokens are always present and expensive. Execution tokens are only paid when activated. Register one skill per domain, not one per capability. Keep router SKILL.md files lean. Push detail into capabilities or references. Prefer a standalone skill until the domain justifies capabilities.

3. Conciseness

The model is already smart. Only add context it doesn't already have. Challenge each piece of information: "Does the model really need this explanation?" See references/authoring-principles.md for detailed guidance.

4. Degrees of Freedom

Match specificity to the task's fragility. High freedom for flexible tasks, low freedom for fragile operations. See references/authoring-principles.md.

5. Write Once, Adapt Everywhere

Domain knowledge is authored exactly once in the canonical layer (skills and roles). When domain knowledge changes, one file changes. Tool-specific deployment pointers, if needed, are optional user-managed customizations — implemented as wrapper files or symlinks. When deploying, always ask the user which mechanism to use. See references/tool-integration.md for the decision guide.

Quick Reference: When to Read What