A skill is a markdown file that teaches an agent how to accomplish a task using your applet’s methods. Skills live alongside the applet at applets/<slug>/skills/<skill-name>.md. They are pure documentation - no code - and ship inside the bundle.

Where methods define what an applet can do, skills describe how to use those methods well: which to call, in what order, and with what constraints.

Shape of a skill

# Find a Credential for a Task Without Revealing the Secret

Decide whether the user already has a credential for a host using
metadata-only lookups.

## When to use this skill
- Agent is about to ask the user to log in; wants to confirm a credential exists first.
- User says "use my GitHub credentials" and the agent must confirm coverage.

## Steps
1. Try the boolean shortcut: `@rightplace/credential.checkExists({ kind, host })`
2. Fall back to host search: `@rightplace/credential.findForHost({ host })`
3. Confirm by metadata: `@rightplace/credential.getMeta({ credential_id })`
4. Hand off; do not read the secret.

## Constraints
- NEVER call `@rightplace/credential.get` (returns the plaintext secret).

Conventions

• One skill per task. Name the file for the outcome, not the method.
• Open with a one-line statement of what the skill achieves and when to use it.
• Reference methods by their canonical name, @<author>/<slug>.<verb>, with the exact params.
• State constraints explicitly: which methods are off-limits, what must be confirmed first, what not to reveal.

How agents find them

Skills are indexed when the bundle installs. When an agent’s task matches a skill’s “when to use” description, the skill is surfaced so the agent follows your intended workflow instead of guessing at the method surface.

Keep skills truthful

A skill must mirror the applet’s real method surface. If a skill documents a call that the applet does not actually make, it teaches agents the wrong contract. Grep your own methods/ and applet.json before writing the examples, and use the exact names and param shapes that exist.