An agent skill is not a persona.
A persona says who the agent pretends to be. A skill says what work should trigger it, how the work should be done, and what output should come back.
That difference is small in language and large in practice.
Public skills make a lab indexable by both humans and machines. They are not marketing pages. They are not hidden prompts. They are small operational interfaces.
A skill is a contract
A good skill behaves like a contract between the user, the agent, and the codebase.
The user brings a situation. The agent decides whether the skill applies. The skill constrains the work so the output is more reliable than a generic response.
That contract needs three parts.
- 01A trigger clear enough for an agent to select it.
- 02A method specific enough to change the work.
- 03An output format reliable enough to compare across runs.
If any part is vague, the skill becomes decorative. It may sound intelligent, but it will not fire at the right time or produce consistent work.
Why triggers matter
Most prompt libraries are written around identity.
They say things like "act as a senior reviewer" or "think like a security engineer." That can help tone, but it is weak as infrastructure. An agent cannot reliably decide when to use a skill if the description only names a role.
A useful trigger names a situation:
- -a pull request before merge
- -an exposed API contract
- -an authentication boundary
- -duplicated code across modules
- -an architecture map requested before refactor
Those situations are operational. They can be detected from the user's request, from file names, from diffs, or from repository structure.
This is why CDLI's public skill descriptions are deliberately direct. They say what the skill does and when to use it. Discovery is part of the design.
Why methods matter
The method is where a skill becomes CDLI-shaped.
Generic best practices are not enough. Every model already knows to avoid long functions, check for errors, and prefer clear names. The useful part is the order of work and the discipline of evidence.
For review and audit skills, that means:
- -start from the diff or exposed surface
- -cite file and symbol evidence
- -separate confirmed issues from unconfirmed risks
- -rank findings by user impact and merge risk
- -avoid guessing when the code does not prove the claim
For architecture work, that means diagram first, then drill into each node. The diagram becomes the shared object. Prose follows structure instead of replacing it.
Why output format matters
A skill should produce work that can be checked.
If every run uses a different shape, the result feels clever but becomes hard to compare. A pinned report structure makes the output easier to review, easier to paste into issues, and easier to hand to another agent.
That does not mean every response should be rigid. It means the important fields should be predictable: summary, evidence, findings, recommendations, open questions, and confidence.
Why the collection starts small
CDLI's first public skill collection starts with six skills because six sharp methods are better than thirty-five loose personas.
The point is not to publish everything. The point is to publish enough to show a standard:
- -review code before merge
- -audit exposed security risk
- -find technical debt and drift
- -refactor without behavior change
- -map architecture before changing it
- -review API contracts before clients depend on them
That set tells a coherent story: understand the system, audit the surface, improve the code, and ship with evidence.
That is the public interface worth exposing first.