SKILL.md is a source document that tells an agent how to approach a reusable task. Its value comes from clear scope, specific instructions, useful examples, and supporting assets. The file alone does not prove safety, successful installation, compatibility, or task quality.
What SKILL.md is for
A Skill packages repeatable domain instructions so an agent can apply a consistent workflow. A useful source file names the job, explains when to use it, defines steps, and makes expected outputs visible.
The best Skills reduce ambiguity without pretending every task can be solved by a rigid template.
Anatomy of a useful Skill
Metadata helps discovery and routing. Instructions shape the workflow. Supporting files can provide scripts, templates, examples, or reference material.
- A specific name and description.
- Clear triggers and situations where the Skill should not be used.
- Inputs, workflow stages, and expected outputs.
- Examples and validation criteria.
- Explicit dependencies, permissions, and limitations.
How to evaluate source quality
Length is not quality. A short, specific Skill can be more useful than a long generic document. Evaluate whether each instruction changes how the agent performs the task.
Look for concrete decision rules, named outputs, domain constraints, examples, and a way to verify completion.
Computed quality is a screen
Documentation depth and specificity help prioritize review, but they do not replace a real task test.
What the file cannot prove
A polished source file cannot prove that linked scripts are safe, that installation succeeds, or that a platform loads every supporting asset as intended.
Claims about compatibility, security, or effectiveness need evidence beyond the document itself.
Source is evidence—not certification
Always inspect commands, dependencies, file access, network behavior, ownership, and the pinned commit.
Frequently asked questions
Is every Markdown instruction file an Agent Skill?
No. A Skill should have a clear reusable job, routing context, and enough structure to improve agent behavior. Generic notes may not provide that.
Can one Skill support several platforms?
The workflow may be portable, but installation and loading behavior vary. Treat multi-platform support as an evidence question.
Skills referenced in this guide
jabrena/plinth
033-architecture-diagrams
Use when you need to generate Java project diagrams — including UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, UML Deployment Diagrams, ER (Entity Relationship) diagrams, and bounded-context diagrams — through a modular, step-based interactive process that adapts to your specific visualization needs. This should trigger for requests such as Generate UML diagram; Create sequence diagram; Create class diagram; Create state machine diagram; Create deployme
minhnv0807/ai-business-skills
05-ad-copy-global
Use when the user needs PAID ad copy for Meta, Google, or TikTok — six variants across TOFU, MOFU, and BOFU using AIDA, PAS, and BAB, respecting each platform character limit and ad policy, with a dropshipping mode. Trigger on 'ad copy', 'write Facebook ads', 'TikTok ad copy', 'Google RSA headlines', 'primary text for this ad', 'my ad copy is not converting'. Also use when the user has a product page and asks what to run as an ad. Not for — organic social captions, see `37-social-caption-global`
minhnv0807/ai-business-skills
18-referral-program-global
Use when customers should bring other customers — one-way versus two-way incentives, reward structure and economics, trigger moments, referral messaging, tracking and attribution, fraud controls, and anti-spam compliance by region: TCPA for US, GDPR for EU, PDPA for SEA, LGPD for LATAM. Trigger on 'referral program', 'refer a friend', 'word of mouth', 'viral loop', 'how do I get customers to bring friends', 'affiliate rewards'. Also use when the user has happy customers and no system to use them
minhnv0807/ai-business-skills
20-client-intake-brief-global
Use when an agency or freelancer takes on a NEW client and needs everything up front — an 11-section intake covering business overview, audience, current marketing, goals, budget, timeline, brand assets, approval process, and success criteria, written for the client to fill in and return. Trigger on 'client intake', 'agency brief', 'onboard a new client', 'discovery call template', 'what should I ask a new client', 'kickoff questionnaire'. Also use when the user just signed someone and does not