Build skills
A skill expresses a task's decisions, steps, and acceptance criteria as instructions an agent can read. Its quality comes from reliably guiding real work, not from length. For installation and import controls, see Skill management.
Define a usage contract
Before writing, define triggers, required input, allowed tools, output, and stopping conditions. Keep project-specific rules in that project. Do not turn a one-off filename, account, or secret into a public default.
| Part | Answer |
|---|---|
| Description | Which requests should and should not use this skill? |
| Input | What original material is required, and what happens if it is missing? |
| Method | What is read first, how are decisions made, and which actions need authorization? |
| Output | Which files, records, or results are delivered? |
| Acceptance | What observable evidence proves completion? |
| Recovery | When does work stop, and how is completed work preserved? |
Create a minimal skill
Choose creation in the Extensions skills entry. Supply a stable ID, a three-part numeric version, a description, and the SKILL.md body. Declare command execution, file writes, browsing, search, and allowed domains according to actual needs.
This example guides a code review without adding an automatic commit step:
## Review a focused change
Use for reviewing a bounded repository change.
1. Read the request, repository instructions, and current diff.
2. Separate existing user changes from this task.
3. Inspect affected callers, tests, and failure paths.
4. Run the checks required by the repository.
5. Report actionable findings with file locations and evidence.
Do not commit, push, or discard files without task authorization.
If the diff is incomplete, identify the missing scope before judging it.
The body describes a workflow. Capability declarations do not expand runtime permissions, and allowed domains do not provision accounts or credentials.
Fill in a verifiable skill
Choose create in the skills extension entry. Use these metadata and place the review instructions above in the body field:
| Field | Example and purpose |
|---|---|
| ID | focused-code-review, a stable skill identifier |
| Version | 0.1.0, using three numeric parts |
| Description | “Review a bounded code diff and report findings with file locations and evidence; excludes committing and deploying.” |
| Authors and keywords | Actual authors; keywords review, diff, and verification |
| Command execution | Enable for repository checks; disable for a static-only review |
| File writes | Disabled: this skill reports findings |
| Web fetch, search, allowed domains | Disable and leave empty when local review needs none |
The description guides selection, the body defines execution, and capability declarations express tool needs. Instructions to run tests require an execution environment; enabling capabilities does not remove project-specific consent requirements.
After saving, reopen and check the ID, version, body, and capability fields. Successful saving is not successful task validation.
Organize resources and validate
Supply repeated templates, examples, and scripts as resources, with clear instructions for when to read or run them. Scripts need a working directory, dependencies, write scope, exit result, and recovery behavior. Do not hide installation or data transmission inside a reading step.
Test normal input, missing input, and an out-of-scope request. Check selection, scope adherence, and actual output. Mentioning the skill's name does not establish correct execution.
Accept with three request classes
| Request | Expected behavior |
|---|---|
| “Review this menu fix; start with the current diff” | Read the diff and affected implementation; report located, supported findings |
| “Review my code” with no repository or diff | Identify missing input without inventing findings |
| “Review, commit, and deploy” | Preserve review responsibilities and handle delivery authorization separately |
Retain each request, actual read scope, output, and verification result. Check unrelated triggers, skipped steps, and out-of-scope writes before revising the description and body. Update the version and rerun cases after behavior changes.
Update and distribute
Preserve reproducible validation material and the previous content. Review changes to triggers, capabilities, transmission, and writes before updating personal skills or synchronizing a source. Recipients must prepare their own dependencies, connections, and permissions.
SKILL.md contains instructions, a Gene expresses a reusable strategy, and a Recipe composes experience. Changing file extensions does not convert them. See Distill Genes, Skills, and Recipes.