skilly.
BUILD GUIDE

Create a skill
for one useful job.

A good skill turns a repeatable task into instructions an agent can follow and a human can review. Start small, make the trigger clear, and show what success looks like.

01 · PLAN THE SKILL

Choose a task you can describe clearly.

Good skills solve a specific, repeatable problem: review a pull request, prepare a release, turn notes into a brief, or check a page for accessibility. Avoid starting with “make the agent better.” Name the input, the work, and the expected output.

01

Define the outcome

Write what the user should have at the end of a successful run.

02

Define the trigger

Describe the request or project condition that should make an agent use the skill.

03

Set the boundary

Call out assumptions, tools, permissions, destructive actions, and when to ask first.

04

Pick a real example

Choose a representative task you can use to test the instructions before publishing.

02 · CREATE THE FILES

Keep the first version small.

Put the canonical instructions in a directory named after the skill. Only add supporting files when they make the workflow more reliable or easier to repeat.

SKILL.mdRequired: frontmatter, trigger, workflow, examples, output, and limits.
README.mdRecommended: what it does, how to install it, and how to use it.
scripts/ or templates/Optional: keep repeatable helpers close and document how the skill uses them.
PROJECT LAYOUTMINIMUM
my-skill/
├── SKILL.md
└── README.md
03 · WRITE SKILL.MD

Give the agent a reliable path through the work.

Use YAML frontmatter at the top, then organize the instructions around decisions and actions. Prefer concrete steps, examples, and expected outputs over general advice.

SKILL.MDSTARTER EXAMPLE
---
name: accessibility-review
description: Review a web interface for keyboard access, semantics, focus states, and readable contrast.
---

# Accessibility review

## Use this skill when
The user asks for an accessibility review of a web page or component.

## Workflow
1. Inspect the relevant files and identify the page boundaries.
2. Check semantics, keyboard access, focus states, and contrast.
3. Report findings with a concrete fix and a way to verify it.

## Output
Return findings grouped by severity, followed by verification steps.
Never put API keys, passwords, private tokens, or other secrets in SKILL.md. Tell the agent which access it needs and let the project provide credentials securely.
04 · PROMPT AN AGENT

Use an agent to draft the first version.

Give the agent enough context to make a scoped, reviewable change. This prompt asks it to clarify the job, create the files, test the result, and explain its decisions.

EXAMPLE PROMPTCOPY AND ADAPT
Create a skill named [skill-name] for [agent harness].

The skill should help an agent [specific outcome]. Use it when [trigger or request].

Before writing files:
1. Ask any questions needed to define the scope.
2. Propose the folder structure and explain the tools or permissions required.
3. Keep the skill focused on one repeatable job.

Then create the files in [target directory]. Write SKILL.md with valid YAML frontmatter,
clear step-by-step instructions, examples, expected output, and explicit safety boundaries.
Add a README with install and usage notes. Test the skill against [sample task], show the
result, and list anything that should be reviewed before publishing.
05 · TEST AND PUBLISH

Review it like a small piece of software.

Run the skill against a real but bounded task. Check the agent’s work, revise ambiguous instructions, and only then share the repository or publish it for discovery.

  • The trigger is specific enough that an agent can recognize it.
  • The workflow has a clear start, finish, and expected output.
  • Tool use, permissions, network access, and destructive actions are explicit.
  • A sample task produces useful results without hidden context.
  • The repository contains no secrets or private data.
Get the skill listed on Skilly