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:
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.
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:
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.
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.
---
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.
---
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.
---
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.
---
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.
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:
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:
Once you’re happy with it, you can install it locally and start using it right away.
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:
my-repo/
└── SKILL.md
my-repo/
├── pr-review/
│ └── SKILL.md
└── changelog/
└── SKILL.md
Then anyone can install it with:
npx skills add your-username/my-skill
or target a specific skill:
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.
Here are the practices that separate good skills from great ones:
Follow these, and your skills will actually get used instead of sitting unused.
That’s the complete handbook.
You now know:
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.