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
04-script-video-global
Use when the user needs a spoken script for short-form video — TikTok, Reels, or YouTube Shorts — with a 3-part hook, second-by-second beats, two A/B variants, shoot notes, and a viral score. Switches between product mode and personal brand mode from the context file. Trigger on 'video script', 'TikTok script', 'Reels script', 'Shorts script', 'what should I say in the video', 'write me a hook for a video'. Also use when the user has a video idea and knows only the topic. Not for — cut and edit
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
17-pricing-strategy-global
Use when a price has to be set or changed — value-based pricing, anchoring, charm pricing, decoy tiers, good-better-best packaging, discount policy, and margin math, with currency psychology for US, EU, SEA, and LATAM plus dropshipping markup and BE-ROAS. Trigger on 'pricing strategy', 'how much should I charge', 'should I raise prices', 'price tiers', 'customers say it is too expensive', 'dropshipping markup'. Also use when the product is not selling and the user suspects price is the reason. N