In 2024, AI coding agents (Claude, Cursor, Copilot, etc.) became capable enough to do real work. Teams started writing long instruction files and system prompts. But there was no standard way to package, share, or discover them. Every team reinvented the wheel.
Today, we’re creating a complete handbook on how the solution to the issue above came about, how to use it, and how it became one of the most useful things in AI right now: Agent Skills and the platform that makes them easy to use — skills.sh.
By the end of this workflow, you will understand:
- What Agent Skills actually are
- How skills.sh works
- How to install and use great existing skills
- How to create your own skills from scratch
- How to share them with your team or the world
- And the best practices so your skills actually get used
This is not Flutter-only. The same system works whether you write Flutter, React, backend code, DevOps, or even content. I’ll use Flutter as one practical example, but everything here is flexible.
Let’s get into it.
What are Agent Skills and skills.sh?
An Agent Skill is a lightweight, open format for giving AI agents specialized knowledge and workflows. At its core, a skill is just a folder that contains a file called SKILL.md.
Here’s the basic structure:
my-skill/
├── SKILL.md ← Required
├── scripts/ ← Optional
├── references/ ← Optional
└── assets/ ← Optional
The SKILL.md file has two parts:
- YAML frontmatter at the top (name + description)
- Markdown instructions below
The description is extremely important. Agents only load the name and description of every skill at startup. When your request matches a skill’s description, the agent then loads the full instructions. This is called progressive disclosure — it keeps the context window clean even if you have dozens of skills installed.
Now, what is skills.sh?
skills.sh is the open directory and CLI for the Agent Skills ecosystem. Think of it as the npm for AI agent capabilities. It was built by Vercel Labs and works across many agents, including Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, and more.
You install skills with a single command:
npx skills add owner/repo
That’s it. The CLI detects which agents you have and installs the skill in the right place.
You can browse popular skills on skills.sh, see a leaderboard, and discover what the community is building.
Discover on skills.sh
- Community leaderboard sorted by installs
- Browse by category, language, or use case
- Official skills from Anthropic, Vercel, and more
Demo of some great skills
Let me show you how this looks in practice.
First, installing a skill is simple; run: npx skills add vercel-labs/agent-skills
Note: You need to have Node.js installed on your machine; download and install it.
You can also install any public repo that contains skills.
Once installed, the agent can automatically use them when relevant.
Here are four strong examples of skills.
Example 1 — PR Review (universal)
---
name: pr-review
description: "Reviews pull requests for bugs, security issues, code quality, and adherence to best practices. Use when the user asks to review a PR, check a diff, or get feedback before merging."
---
This one works on any codebase.
Example 2 — Flutter Widget Test (our case study)
---
name: flutter-widget-test
description: Generates high-quality Flutter widget tests following best practices. Use when the user asks to write tests for a Flutter widget, create widget tests, or improve test coverage for UI components.
---
This shows how you can encode framework-specific knowledge.
Example 3 — Generate Changelog
---
name: generate-changelog
description: Generates clean, professional changelog entries or release notes from git commits or PR descriptions. Use when the user asks for a changelog, release notes, or version summary.
---
Super practical for any project.
Example 4 — Brand Voice (non-code example)
---
name: brand-voice
description: Writes content following a consistent professional brand voice. Use when creating LinkedIn posts, Twitter/X threads, blog intros, product announcements, or any marketing copy.
---
This proves skills are not only for code. You can package writing style, design systems, internal processes — anything repeatable.
Build your own skill
This is the most important part of the workflow.
Creating a skill is straightforward.
Step 1: Create a folder and the required file
mkdir my-skill
touch my-skill/SKILL.md
Step 2: Write the frontmatter
The two required fields are name and description.
The description is what the agent uses to decide whether to activate the skill. Be specific. Include the kind of phrases a real user would say.
---
name: my-skill-name
description: What it does and when to use it.
Include real trigger phrases here.
---
Step 3: Write clear instructions
Good structure usually includes:
- When to use this skill
- When not to use it
- Step-by-step process the agent should follow
- Expected output format
- Any edge cases or rules
Write it like you’re explaining it to a smart new teammate.
Step 4: Test with real prompts
Install locally with npx skills add ./my-skill then trigger it with exact phrases. If it doesn't activate, the description needs to be more specific.
Key tips while creating:
- Start small. A focused 15–30 line skill is better than a long vague one.
- Make the description do the heavy lifting for activation.
- Write instructions the way you would explain the task to a smart junior developer.
- Test it immediately after creating it.
Once you’re happy with it, you can install it locally and start using it right away.
Share your skills
You have two main ways to share.
1. With your team / private
Just commit the skills folder into your repository. Everyone who clones the project gets the skills.
2. Publicly with skills.sh
Push the skill to a public GitHub repository. You have two common structures:
- Dedicated repo → SKILL.md sits at the root
- Multi-skill repo → skills live in subfolders
# Single skill
my-repo/
└── SKILL.md
# Multi-skill
my-repo/
├── pr-review/
│ └── SKILL.md
└── changelog/
└── SKILL.md
Then anyone can install it with:
# Public: single-skill repo
npx skills add your-username/my-skill
or target a specific skill:
# Public: multi-skill repo
npx skills add you/repo --skill name
You can also add the skills.sh badge to your README so people can see install counts.
Clear name + excellent description = more people will find and use your skill.
Best Practices
Here are the practices that separate good skills from great ones:
- Write trigger-friendly descriptions — this is the #1 factor for reliable activation.
- Keep skills focused — one clear job per skill. Compose multiple skills instead of making one giant skill.
- Use progressive disclosure properly — put long references or examples in separate files.
- Document when not to use the skill.
- Test with real phrasing — try the exact words your users (or you) would actually type.
- Treat skills like code — version them, review them, improve them over time.
- Only install skills from sources you trust — always skim the SKILL.md and any scripts.
- For teams — store shared skills in the repo so consistency is automatic.
Follow these, and your skills will actually get used instead of sitting unused.
That’s the complete handbook.
You now know:
- What Agent Skills are and how progressive disclosure works
- What skills.sh is and how to install skills
- How to demo and evaluate existing skills
- How to create your own
- How to share them
- And the best practices that make them effective
The biggest shift is this: instead of repeating the same instructions in every chat, you package the knowledge once and let any compatible agent use it.
If you create a skill after reading this, drop the GitHub link in the comments. I’d love to see what you build.
If you found this valuable, hit like, subscribe, and turn on notifications.
I also offer 1-on-1 mentorship if you want help setting up skills or AI workflows for your team — click here.
I’ll see you in the next one. Peace.
Top comments (0)