---
name: skill-writing
description: Author and maintain skills for this shared library. Use when adding or reviewing a library skill, revising its instructions, or consolidating repository guidance into a reusable library skill.
license: MIT
---

# Skill writing

Build reusable instructions from actual tasks and source material. Include only
guidance that changes an agent's decisions or gives it knowledge it lacks.

## Establish scope and ownership

Identify the requests, required inputs, output, and observable result. Use
available context; ask only for missing information that would change the skill.

Before rewriting, read the existing skill, relevant agent instructions, examples,
helpers, and task corrections. Preserve useful constraints and their reasons.
Combine duplicates and resolve conflicts using ownership, evidence, and the
user's direction.

Inspect callers and provenance. Edit the maintained source; use existing
generators and installers for generated or installed copies. Preserve useful
resources and supported metadata. Prefer an upstream package's update mechanism
when it meets the need. Adapt it for a concrete requirement, retain attribution
and compatible licensing, and explain material changes.

## Write the skill

Honor the requested or maintained location. Use a directory named `<name>`
containing `SKILL.md`, with `name` and `description` in YAML frontmatter and
instructions in the Markdown body. For example, in `meeting-actions/SKILL.md`:

```markdown
---
name: meeting-actions
description: Extract decisions and actions. Use when summarizing supplied meeting notes.
---

# Meeting actions

Read the notes. Separate decisions from proposals.
List owners and dates only when stated; flag unclear assignments.
Return a draft action list in the requested format.
```

Use a matching lowercase name of 1–64 letters, digits, and hyphens, with no
consecutive, leading, or trailing hyphens. The description must be 1–1,024
characters and explain the capability and when to use it. Avoid broad triggers
that capture unrelated work.

Describe the inputs, decisions, procedure, and result. Specify fragile sequences
precisely; leave room for judgment where several approaches work. Keep only
instructions that affect the task. Remove repetition and generic advice. Put
long examples and conditional detail in `references/`, linked directly from
`SKILL.md`, and load them only when needed. Keep the body well below the upstream
recommendation of 500 lines and 5,000 tokens. A simple skill can be one file.

Keep application facts and credentials with their owner. Name each private input
through an argument, supplied context, existing setting, or authenticated tool
connection. Explain its purpose and what to do when absent. Keep secrets out of
examples and logs; avoid assumed home paths and unrelated credential searches.

State actual tool requirements, check availability when needed, and provide a
supported fallback or limitation. Keep installation and execution permissions
specific to the consumer. Check the current [specification](https://agentskills.io/specification)
and consumer before changing optional metadata: fields such as `allowed-tools`
can preapprove tool use. Preserve the user's authority. Drafting does not
authorize sending, publishing, deploying, deleting, or changing configuration.
An integration skill does not own its server deployment. Require Git or PRs only
when the task needs them.

## Add resources when they help

- `references/`: conditional procedures and substantial examples. Link each where
  needed and say when to read it.
- `assets/`: templates or other files copied into outputs.
- `scripts/`: repeated or fragile mechanics an existing tool does not cover.
  Document dependencies and inputs; exercise changed helpers on disposable data.

Resolve bundled paths relative to the skill directory as supported by the
consumer. Avoid empty folders, copied manuals, duplicate instructions, and
routing layers for a single procedure. See [examples](references/examples.md)
when deciding how to express private inputs, scope, or preserved intent.

## Verify behavior

1. Run `skills-ref validate <skill-directory>` and any additional repository
   checks. Resolve bundled links and exercise changed scripts.
2. For new or substantially revised skills, try realistic requests with raw
   inputs, including a nearby request that should not activate the skill and
   relevant missing-input or failure cases. Compare prior behavior where useful.
   For small edits, check the affected behavior.
3. For substantial, complex, or risky skills, consider an independent agent when
   it adds confidence and delegation is available and authorized. Supply the
   skill, request, permitted resources, and raw artifacts without the expected
   answer. Keep artifacts temporary and prevent live side effects. Small edits
   do not require delegation.
4. Inspect the output and actions for preserved intent, facts, attribution,
   required format, and authorization boundaries. Revise demonstrated problems.

Record what was tested and its limits. Format checks alone do not establish
behavior or support for untested consumers. See [sources](references/sources.md)
for provenance and current upstream guidance.