Creating Skills
Skill authoring has one canonical user-facing entry:
Use this developer page for implementation boundaries.
When To Add A Skill
Create a skill when the capability can be expressed as reusable instructions, supporting files, and existing tools.
Add a runtime tool only when Anyy needs new executable behavior or a new policy-governed side effect.
Runtime Loading
Skill parsing and management live under internal/skills. Runtime resolution,
visibility, command descriptors, and active-skill prompt material live under
internal/runtime/skills and gateway skill glue.
Skills are profile-scoped. Roles do not own skill roots or permissions.
Skill Files
A skill is usually rooted at SKILL.md with optional supporting files. Managed
skills live in the profile home; configured external roots are read-only unless
the manager explicitly installs into the managed root.
Do not treat workspace-local files as product identity or trusted policy.
Commands
Skills can declare commands. Runtime turns those declarations into
protocol.CommandDescriptor values while respecting reserved command names and
surface/channel filters.
Commands activate skills; they do not bypass tool governance.
Validation
Tests should cover parser behavior, root precedence, reload, management tools, command descriptors, active-skill prompt inclusion, and redaction.
Keep skill examples small and avoid secrets in fixtures.