What a SKILL.md file is
A Skill is a directory containing a SKILL.md instruction file written in natural language. When an agent installs a Skill, it reads that file to learn when to use the Skill, what steps to take, and what it depends on. No compilation step, no SDK — the file is the program.
The naming convention is not perfectly standardised in the wild. Two of the three reports we rely on write SKILL.md; one writes skill.md. We write the uppercase form, and you should check which one the target agent expects rather than assume.
The three sections that decide the outcome
Reported behaviour of the official publishing flow is that the creator console parses your Markdown and extracts a name, a short description and the body automatically, then asks you to supply the identifier by hand before an approval step. That shape tells you what gets read first.
- The trigger blockWhen should this Skill fire? If a reviewer cannot answer that from the first paragraph, nothing else in the file will rescue it. Name the situation, not the technology.
- The step listWhat exactly happens, in order, and where the human is asked to confirm. A step list with no confirmation point reads as an unattended automation, which is a harder thing to approve than a draft-and-review loop.
- The dependency blockWhat must already exist for this to work: tools, credentials, file paths, network access, a logged-in session. This is the section authors skip and reviewers need most.
Writing triggers that fire at the right moment
Vague triggers are the most common defect in the Skills we have read. "Helps with content" will fire in the middle of an unrelated task and produce noise. "Use when the user asks to turn a product page into three Xiaohongshu note drafts with a hook, a body and a call to action" fires when it should and stays quiet otherwise.
Three rules that hold up in practice:
- Name the artefact, not the vibe. "A product page", "a CSV export", "a screenshot of a comment thread" — concrete inputs make the trigger testable.
- Include the negative case. One sentence saying when not to use the Skill prevents more bad runs than three sentences of positive description.
- Say what the output is. If the Skill produces a draft, say "draft". If it produces something that gets published, say that too — and say that a human confirms first.
Being honest about dependencies
The most consequential dependency is a session. Reporters documented an install flow where a Skill drives a real logged-in browser, and repositories in our dataset that state this plainly are the easy ones to evaluate. State it the same way you would state a database requirement — as a precondition, not a footnote.
The second thing to get right is what the platform will actually accept today. Reported behaviour of the creator console: only Markdown is parsed, and script files are filtered out, so a Skill that needs Python or Node has to say what to do when the script is not there. Writing "requires Python" without that fallback leaves every reader with a Skill that half-runs.
A skeleton you can start from
Nothing here is official syntax — no source we could reach documents a required schema. It is the structure that has survived being read by both people and models.
# <Skill name>
## When to use this
- Use when: <the artefact and the goal>
- Do not use when: <the neighbouring task this would misfire on>
- Output: draft | checklist | report | published action (state which)
## Inputs you need from the user
- <input> — required / optional, and what it looks like
## Steps
1. <action>
2. <action>
3. STOP and show the result to the user before continuing
## Dependencies
- Tools: <interpreter, CLI, model>
- Session: none | read-only public pages | logged-in browser
- Network: none | public read | authenticated write
## Failure handling
- If <dependency> is missing: <what to do instead>
- Never: <the action this Skill must not take>
The submission path
Publishing runs through the Xiaohongshu creator console, and it is web-only — the app is not supported for upload. The reported sequence: open the creator console, choose the Red Skill entry, upload a single Markdown file or a folder containing Markdown, let the system parse the name, description and body, fill in the identifier yourself, then submit for approval. After approval a note can carry the Skill as an attachable component.
Two operational facts worth planning around. Upload was in a grayscale rollout while the copy-passphrase feature was open to everyone, so availability may vary by account. And the identifier is not auto-generated: choose something you can still parse in six months, because it is what every install command will contain.
Pre-submission checklist
- Can a stranger predict the trigger?Read only your "When to use" block and decide whether you could say when it fires and when it does not.
- Is there a confirmation point?Any step that changes something outside your own machine needs a human gate written into the file.
- Is the session requirement stated?If it needs a logged-in browser, that is the first line of the dependencies block.
- Does it survive a missing dependency?Every dependency should be paired with a "what to do instead" line, even if the answer is "stop and tell the user".
- Are the inputs named concretely?"A product page" beats "some content". Reviewers install the Skill and test it with whatever you wrote.
- Does it say what it will never do?An explicit never-list is the cheapest trust signal a Skill file can carry.