Agent Skills Are Trending on GitHub: What a SKILL.md File Is and How to Use One
Skill and plugin repos filled GitHub's weekly trending list. Here is what a SKILL.md file contains, how agents load it, and how to install one.

GitHub's trending page usually turns up frameworks, small libraries, and the occasional database engine. The week of October 21, 2026 was different. Several of the entries were skill and plugin repositories, including Anthropic's official Claude Code plugin directory, the Cursor plugin specification, Android's skills repo, and a science-focused library of agent skills. A SKILL.md file is a much smaller thing than the word plugin suggests, so it is worth ten minutes to understand what is actually trending and why.
What showed up on the trending page
The repos that landed on GitHub's weekly trending list during the week of October 21, 2026 each describe themselves differently:
- anthropics/claude-plugins-official calls itself an "Official, Anthropic-managed directory of high quality Claude Code Plugins".
- cursor/plugins holds the Cursor plugin specification and official plugins.
- android/skills is Android's own skills repository.
- K-Dense-AI/scientific-agent-skills describes itself as an Agent Skills library for science, compatible with Cursor, Claude Code, Codex, and other tools that follow the open Agent Skills standard.
Read those descriptions together and a pattern shows up. Several vendors are publishing the same kind of unit: a folder holding instructions, designed to be picked up by a coding agent. The naming differs from tool to tool. The shape is the same, and the shape is small enough to learn in one sitting.
What a skill actually is
A skill is a folder with a SKILL.md file at its root. The file starts with YAML frontmatter, then the body of the skill. The frontmatter tells the agent what the skill is called and when it might be useful. The body tells the agent what to do.
Here is a complete example:
---
name: release-notes
description: Turn a list of merged pull requests into customer-facing release notes. Use when asked to write changelog entries or summarize what shipped this week.
license: MIT
metadata:
version: "1.2.0"
---
# Release notes
## Inputs
- The list of merged pull requests for the target week
- The previous release notes, for tone and format
## Steps
1. Group the pull requests by user-visible change, not by internal module.
2. Write one sentence per change. Lead with the effect on the user, not the implementation.
3. Drop anything a user would not notice, including refactors, test changes, and dependency bumps.
4. Keep the order stable: features first, fixes second.
## Output format
- A short intro paragraph, no more than two sentences.
- Bullet list, one bullet per change, past tense.
- A "Known issues" section only when a listed item is still open.Two fields are required: name and description. Everything else is optional.
The name has rules that tools validate strictly, so it is worth getting right the first time:
- 1 to 64 characters.
- Lowercase letters and numbers separated by single hyphens. The pattern is `^[a-z0-9]+(-[a-z0-9]+)*$`, so `code-review` passes and `code_review` does not.
- It has to match the folder name. A folder called `code-review` holding a skill named `code-review` is the arrangement that survives validation.
The description can run from 1 to 1024 characters, and it is the part the agent reads before deciding whether to open the skill. Write it as a trigger rather than a summary. Say when to use the skill, in the words a user would actually type, because that is what the agent matches against.
The optional fields
- license: the license that covers the skill.
- compatibility: a note about which tools or versions the skill targets.
- metadata: a map of string keys to string values, such as a version.
How an agent finds and loads a skill
OpenCode's documentation describes the loading model plainly. The agent is given the list of skill names and descriptions. It does not pull the body of every installed skill into context. When a task matches one, the agent calls a skill tool and loads the full content on demand.
That design is what makes a large library cheap. Twenty installed skills cost twenty lines of names and descriptions until one of them is actually needed.
OpenCode searches six locations:
- `.opencode/skills` inside the project.
- `~/.config/opencode/skills` for the current user.
- `.claude/skills` inside the project.
- `~/.claude/skills` for the current user.
- `.agents/skills` inside the project.
- `~/.agents/skills` for the current user.
Four of those paths are not OpenCode specific. `.claude/skills` and `.agents/skills`, in the project and in your home folder, are the Claude-compatible and agent-compatible locations, so a skill kept there is not locked to OpenCode. The same open Agent Skills format is what the science library above says it follows.
Permissions live in `opencode.json`, and they can allow, deny, or ask per skill name pattern. A denied skill is hidden from the agent, and an ask rule makes the agent get your approval before it loads that skill.
Installing skills from GitHub
Writing a skill by hand takes a minute. Installing one takes two commands:
npx skills find release notes
npx skills add owner/repoThe `skills find` command searches the catalog hosted at skills.sh, and `skills add` pulls the skill from a GitHub repository into the place your agent looks for skills. Because the repository is where the skill lives, it is also where you read it before installing.
Writing a skill that holds up
- Give it one job. A skill that covers three tasks becomes a document the agent half-follows.
- Write the description as a trigger, and include the words a user would actually type.
- List the inputs first, then the steps in order, so the agent does not have to guess what to collect.
- Show the output format. A worked example removes more guesswork than another paragraph of prose.
- Keep the body short enough to read in one pass. If it runs long, split the reference material into a separate file the skill points to.
The example above follows that shape: inputs, numbered steps, output format. Nothing else. A skill that a person can follow on a first read is a skill an agent can follow too.
A skill runs with the agent's permissions
This is the part worth slowing down on. A skill is instructions the agent will follow, and it runs with whatever the agent can already do. If the agent can read your files, run shell commands, and call your API, then a skill can tell it to do those things. The skill does not get its own sandbox.
Before you install one:
- Read the SKILL.md first, and every file in the folder including any script it references.
- Look for anything that reaches for credentials. A skill that asks for an API key, a token, or a password is a reason to walk away.
- Treat the shell commands and network calls inside a skill the way you would treat them in a pull request from a stranger.
- Keep a permission rule for anything that writes outside the project directory.
The catalog is large and it grows every week, so the quality of any one skill is set by whoever published it. Reading the file is the whole review process, and it takes about the same time as installing it.
How Tolz.me uses skills
Tolz.me runs on skills. The repository holds one skill per job: writing and updating tool pages with their SEO metadata, generating FAQs and use cases, humanizing copy before it ships, and registering tools so browser agents can find them. Each one is a folder with a SKILL.md, checked in next to the code it maintains.
The payoff is repeatability. A new tool page in the Tolz.me tools directory gets the same metadata structure, the same FAQ shape, and the same pass over the writing, whether a person or a coding agent is doing the work.
If you are setting up skills for the first time, a small utility with clear rules makes a good first target, since the right answer is easy to check. The Cron expression translator fits that description. For the other half of the problem, what happens after an agent writes the code, our guide on shipping AI-written code you don't understand covers the review side.
What to take away
A skill is a folder with a SKILL.md. Two required fields, a few optional ones, a name that has to match the folder, and a description that decides whether the agent ever opens the file. The agent sees the list, loads what it needs, and runs it with your permissions. That last part is the whole security story, and it is the reason to read the file before installing it.