What a reader needs to see before choosing a skill
You have a skill that does what you need. This guide is about the pages around it: the README, the license line and the listing text, written for someone who has never seen your repository.
Three readers, three pages
SKILL.md is for the agent. Its name and description tell the agent what the skill does and when to use it.
The README is for a person who opens your repository. They want to know what it does, what they need and how to start.
A listing is for a person comparing. They may have two or three similar options open in other tabs.
Each page answers a different question. Keep them separate, and keep them in agreement.
Start with the outcome
One sentence: what the reader gets, and for whom. Use no adjective a reader cannot check.
- Vague: "Helps with document tasks."
- Clear: "Turns [input] into [output] for [role], using [named format]."
Say who it is for
Name the role and the starting point: "[Role] who already [does the task by hand]." Then give two to four example tasks, including one it does not handle, and why.
Requirements and setup
Name the AI tool the skill is written for, and the version or feature it needs. Say what you have run it on, with a date, and what you have not run it on.
The specification has an optional compatibility field for environment requirements, such as the intended product, system packages or network access.
List what a reader needs before step one: accounts, tools and versions. Then write the steps from a clean start, in order, and end with what the reader should see when it worked.
What it can read, change or send
Say what the skill reads, writes, changes, deletes, sends or runs. Name the folders, accounts and network destinations it touches, and the tools it asks the assistant to use. Say which kind of credential a reader must supply, never a real value.
- "Reads: [folder you point it to]. Writes: [output location]. Network: [service and purpose], or none. Does not: [delete, send or publish anything]."
Write a "does not" only if it is true of the version you share.
Limits, in your own words
Write the limits before the benefits. "Results may vary" tells a reader nothing.
- "Handles [X]. Does not handle [Y]. With [condition], the output can be wrong; check [what] before you rely on it."
License
The specification has an optional license field: a license name, or the name of a license file bundled with the skill.
license: [license name]license: [license name]. [LICENSE file] has the full terms.
Use the same name in the README and in any listing, and keep the full text in the repository. Then say in plain words what a reader may do: use it, change it, share it, and with what attribution. If you include someone else's material, name its license and keep its notice.
Data
Say what the skill reads, what it sends elsewhere and to whom, and what it keeps after a session. Name each destination. Use invented sample values in every example.
Never include private prompts, credentials, personal records or confidential datasets.
Read it as a stranger
Open your page as someone who has never seen the repository. Can they answer these from the page alone?
- What will this do, and for whom?
- Which tool is it written for, and what must I set up?
- What can it read, change or send?
- What does it not do?
- What may I do with it?
Where a question has no answer, the reader has to guess. Answer it in plain words, including the parts that do not flatter the skill.
On Skills Outpost
Skills Outpost is a catalog of ready-made agents and skills. Every listing is provided by a creator, and Skills Outpost does not run agents.
Your code can stay where it is. A source code link is optional and must point to github.com, gitlab.com or codeberg.org (or a subdomain of one of them).