Skills

A skill is a package that teaches an agent when to take on a type of work and how to complete it. Its canonical entry point is SKILL.md; the package may also contain workflows, references, scripts, and assets.

​

Two jobs

Every skill has two distinct jobs:

1. Activation: help the agent recognize when this skill applies.
2. Execution: guide the agent toward a correct, verifiable result.

A skill can fail either job. If the agent never selects it, improving the workflow body will not fix activation. If it activates correctly but produces a weak result, adding trigger phrases will not fix execution.

​

Source and installed copies

Before changing a skill, identify its canonical source and the installed copy the agent actually reads. A repository source, global installation, project installation, immutable Library revision, and Cloud snapshot may represent different versions. SelfTune should always report which revision it observed, tested, changed, or published.

​

What good evidence looks like

Test requests that should activate the skill, nearby requests that should not, and realistic tasks that exercise its workflow. Real usage can reveal language and failure modes that the original author did not anticipate. Synthetic tests are useful, but they should be identified as generated evidence. Continue with Evidence and health or Improve a skill.