skilly.
PUBLISHER GUIDE

Make your skill
easy to understand.

Skilly’s directory is only as useful as the information publishers put into their skill files. Clear frontmatter and focused instructions help people find the right capability and trust what they install.

SKILL.MD FRONTMATTER

Start with a precise description.

Use YAML frontmatter at the top of SKILL.md. The name should be recognizable; the description should say what the skill does, when to use it, and what outcome it helps produce.

SKILL.MDFRONTMATTER
---
name: accessibility-review
description: Review a web interface for keyboard access, semantics, focus states, and readable contrast.
---
GET LISTED ON SKILLY

Publish upstream, then let Skilly sync it.

Skilly mirrors the public catalog from skills.sh; there is no separate Skilly submission form. Make the skill discoverable upstream, then Skilly imports it during the next successful catalog refresh.

01

Use a public GitHub repository

Keep the repository and the skill source public so the catalog can read the pinned Git revision and link people back to the original instructions.

02

Use the canonical layout

For the most reliable discovery, put the file at skills/<skill-name>/SKILL.md. Keep the filename exactly SKILL.md, and make the directory name match the skill name.

03

Publish through the upstream flow

From the repository root, validate with gh skill publish --dry-run, then publish a release with gh skill publish --tag v1.0.0. If your GitHub CLI does not provide this command, follow the current publishing instructions on skills.sh.

04

Confirm both listings

Check the skill’s skills.sh page first. Once it is present there, Skilly’s scheduled sync will import it; search the Skilly directory after the refresh.

RECOMMENDED LAYOUTGITHUB
your-repo/
└── skills/
    └── accessibility-review/
        └── SKILL.md
Skilly requires valid YAML frontmatter with a lowercase hyphenated name and a non-empty description. Keep the folder name, frontmatter name, and upstream skill slug aligned.
THE INSTRUCTIONS

Write for a capable agent and a careful human.

01

State the trigger

Explain the kind of request or project condition that should make an agent use the skill.

02

Make the workflow concrete

Prefer ordered steps, decision points, examples, and expected outputs over broad advice.

03

Call out boundaries

Name destructive actions, required tools, assumptions, and cases where the agent should ask first.

SUGGESTED STRUCTURE

Give the reader a map.

SKILL.mdFrontmatter, purpose, workflow, examples, limits.
README.mdRepository context, install notes, ownership, and contribution details.
Supporting filesKeep scripts and templates close, named clearly, and documented from the skill.
BEFORE YOU PUBLISH

A small quality checklist.

  • The name tells a user what capability they are getting.
  • The description includes useful search language, not just a slogan.
  • The instructions have a clear start, finish, and expected output.
  • Commands, tools, permissions, and destructive operations are explicit.
  • The repository uses a public source and a discoverable SKILL.md path.
  • No credentials, personal data, or hidden network behavior are included.
See the directory