Agent Skills

This stuff smells like maybe the bitter lesson isn't fully appreciated.

You might as well just write instructions in English in any old format, as long as it's comprehensible. Exactly as you'd do for human readers! Nothing has really changed about what constitutes good documentation. (Edit to add: my parochialism is showing there, it doesn't have to be English)

Is any of this standardization really needed? Who does it benefit, except the people who enjoy writing specs and establishing standards like this? If it really is a productivity win, it ought to be possible to run a comparison study and prove it. Even then, it might not be worthwhile in the longer run.

Our team has found success in treating skills more like re-usable semi-deterministic functions and less like fingers-crossed prompts for random edge-cases.

For example, we have a skill to /create-new-endpoint. The skill contains a detailed checklist of all the boilerplate tasks that an engineer needs to do in addition to implementing the logic (e.g. update OpenAPI spec, add integration tests, endpoint boilerplate, etc.). The engineer manually invokes the skill from the CLI via slash commands, provides a JIRA ticket number, and engages in some brief design discussion. The LLM is consistently able to one-shot these tickets in a way that matches our existing application architecture.

For devtools cos providing skills - we've found that using GEPA where you optimize the skill content instead of the prompt works really well to make sure the skill actually gets claude code/ codex /opencode to successfully use your service. https://arxiv.org/abs/2507.19457 More here if interesting https://www.usesynth.ai/blog/environment-pools-managed-agent...

Please standardize the folder.

  .claude/skills
  .codex/skills
  .opencode/skills
  .github/skills

Pro tip: create README.md files in subfolders with helpful content that you might put in an AGENTS.md file (but, ya know, for humans too), and *link relevant skills there*. You don't even have to call them skills or use the skills format. It works for everything (including humans!).

I wrote a rant about skills a while ago that's still relevant in some ways: https://sibylline.dev/articles/2025-10-20-claude-skills-cons...

The observation about agents not using skills without being explicitly asked resonates. In practice, I've found success treating skills as explicit "workflows" rather than background context.

The pattern that works: skills that represent complete, self-contained sequences - "do X, then Y, then Z, then verify" - with clear trigger conditions. The agent recognizes these as distinct modes of operation rather than optional reference material.

What doesn't work: skills as general guidelines or "best practices" documents. These get lost in context or ignored entirely because the agent has no clear signal for when to apply them.

The mental model shift: think of skills less like documentation and more like subroutines you'd explicitly invoke. If you wouldn't write a function for it, it probably shouldn't be a skill.

My unproven theory is that agent skills are just a good way to 'acquire' unspoken domain rules. A lot of things that developers do are just in their heads, and using 'skills' forces them to write these down. Then you feed this back to the LLM company for them to train on.

Does anyone find that agents just don't use them without being asked?

I'm developing a new programming language, so I have to provide a way for LLMs to know about and generate code for a language they have not seen (i.e., have no training data for).

My tooling was previously adding in AI hints with CLAUDE.md, Cursor Rules, Windsurf Rules, AGENTS.md, etc., but I recently switched to using only AGENTS.md and SKILLS. I appreciate the standardization from this perspective.

The third most popular skill on skills.sh[1] with 50k/week installs is a link to download a command[2]

[1] https://skills.sh/vercel-labs/agent-skills/web-design-guidel... [2] https://github.com/vercel-labs/agent-skills/blob/main/skills...

All of these SKILLS.md/AGENTS.md/COMMANDS.md are just simple prompts, maybe even some with context links.

And quite dangerous.

The real value isn't the format itself — it's progressive disclosure. When you dump everything into one monolithic doc, you're burning context tokens on instructions the agent doesn't need for the current task.

Skills as a pattern let the agent scan a lightweight index of descriptions, then pull in the full instructions only when relevant. Whether that's a .skills/ folder or a README index pointing to separate docs doesn't matter much. What matters is the separation between "what capabilities exist" and "how to execute this specific one."

The standardization part is mostly useful for distribution — being able to install and share skills across projects without manually wiring them up. Same reason we standardize package formats even though you could just copy-paste code.

I am working on a domain specific agent that includes the concept of skills. I only allow one to be active at a time to reduce the chances for conflicting instructions. I use a small sub-agent to select/maintain/change the active skill at the start of each turn. It uses a small fast model to match the recent conversation to a skill (or none). I tried other approaches, but for my use case this was worked well.

My model for skills is similar to this, but I extended it to have explicit use when and don’t use when examples and counter examples. This helped the small model which tended to not get the nuances of a free form text description.

I started playing with skills yesterday. I'm not sure if it's just easier for the LLM to call APIs inside the skill — and then move the heavier code behind an endpoint that the agent can call instead.

I have a feeling that otherwise it becomes too messy for agents to reliably handle a lot of complex stuff.

For example, I have OpenClaw automatically looking for trending papers, turning them into fun stories, and then sending me the text via Telegram so I can listen to it in the ElevenLabs app.

I'm not sure whether it's better to have the story-generating system behind an API or to code it as a skill — especially since OpenClaw already does a lot of other stuff for me.

Awesome Agent Skills: https://github.com/skillmatic-ai/awesome-agent-skills

I think pre-canned "skills" are an anti-pattern with the frontier models. Arguably, these skills already exist within the LLM. We don't need to explain how to do things they already know how to do.

I prefer to completely invert this problem and provoke the model into surfacing whatever desired behavior & capability by having the environment push back on it over time.

You get way more interesting behavior from agents when you allow them to probe their environment for a few turns and feed them errors about how their actions are inappropriate. It doesn't take very long for the model to "lock on" to the expected behavior if you are detailed in your tool feedback. I can get high quality outcomes using blank system prompts with good tool feedback.

I don't think a general public set of skills like this is going to work. I see value in vendors producing skills for their own products, and end users maintaining skills to influence agents according to their preferences, but too much in these skills files is opinion. Where does this end? Ordering of skills by specificity, such as org > user > workspace? And we know that skills aren't reliably picked up anyway. And then there's the additional attack surface area for prompt injection.

I use a common README_AI.md file, and use CLAUDE.md and AGENTS.md to direct the agent to that common file. From README_AI.md, I make specific references to skills. This works pretty well - it's become pretty rare that the agent behaves in a way contrary to my instructions. More info on my approach here: https://www.appsoftware.com/blog/a-centralised-approach-to-a... ... There was a post on here a couple of days ago referring to a paper that said that the AGENTS file alone worked better than agent skills, but a single agents file doesn't scale. For me, a combination where I use a brief reference to the skill in the main agents file seems like the best approach.

Implementation Notes:

- There is no reason you have to expose the skills through the file system. Just as easy to add tool-call to load a skill. Just put a skill ID in the instruction metadata. Or have a `discover_skills` tool if you want to keep skills out of the instructions all together.

- Another variation is to put a "skills selector" inference in front of your agent invocation. This inference would receive the current inquiry/transcript + the skills metadata and return a list of potentially relevant skills. Same concept as a tool selection, this can save context bandwidth when there are a large number of skills

A link from a couple weeks back suggests that putting them in first-person makes them get adopted reliably. Something like, "If this is available, I will read it," vs "Always read this." Haven't tried it myself, but plan to.

I'm not disagreeing with standards but instead of creating adapters, can't we prompt the agent to create its own version of a skill using its preferred guidelines? I don't think machines care about standards in the way that humans do. If we maintain pure knowledge in markdown, the agents can extract what they need on demand.

Started to work on a tool to synchronize all skills with symlinks. Its ok for my needs at the moment but feel free to improve it its on GH: https://github.com/Alpha-Coders/agent-loom

Please help me understand. Is a "skill" the prompt instructing the LLM how to do something? For example, I give it the "skill" of writing a fantasy story, by describing how the hero's journey works. Or I give it the "curl" skill by outputting curl's man page.

I think skills are probably a net positive for the general population, but for power users, I do recommend moving one meta layer up --

Whenever there's an agent best practice (skill) or 'pre-prompt' that you want to use all the time, turn it into a text expansion snippet so that it works no matter where you are.

As an example, I have a design 'pre-prompt' that dictates a bunch of steering for agents re: how to pick style components, typography, layout, etc. It's a few paragraphs long and I always send it alongside requests for design implementation to get way-better-than-average output.

I could turn it into a skill, but then I'd have to make sure whatever I'm using supported skills -- and install it every time or in a way that was universally seen on my system (no, symlinking doesn't really solve this).

So I use AutoHotkey (you might use Raycast, Espanso, etc) to config that every time I type '/dsn', it auto-expands into my pre-prompt snippet.

Now, no matter whether I'm using an agent on the web/cloud, in my terminal window, or in an IDE, I've memorized my most important 'pre-prompts' and they're a few seconds away.

It's anti-fragile steering by design. Call it universal skill injection.

I realized that amp uses ~/.agents/skills

I liked that idea to have something more CLI agnostic

I noticed a couple days ago https://skill.md started redirecting to this new URL.

Experimenting with skills over the last few months has completely changed the way I think about using LLMs. It's not so much that it's a really important technology or super brilliant, but I have gone from thinking of LLMs and agents as a _feature_ of what we are building and thinking of them as a _user_ of what we are building.

I have been trying to build skills to do various things on our internal tools, and more often then not, when it doesn't work, it is as much a problem with _our tools_ as it is with the LLM. You can't do obvious things, the documentation sucks, api's return opaque error messages. These are problems that humans can work around because of tribal knowledge, but LLMs absolutely cannot, and fixing it for LLM's also improves it for your human users, who probably have been quietly dealing with friction and bullshit without complaining -- or not dealing with it and going elsewhere.

If you are building a product today, the feature you are working on _is not done_ until Claude Code can use it. A skill and an MCP isn't a "nice to have", it is going to be as important as SEO and accessibility, with extremely similar work to do to enable it.

Your product might as well not exist in a few years if it isn't discoverable by agents and usable by agents.

Is there a skill directory that can be browsed by a human?

Interesting format, but skills feel like optimizing the wrong layer. The agents usually don't fail because of bad instructions — they fail because external systems treat them like bots.

You can have the perfect scraping skill, but if the target blocks your requests, you're stuck. The hard problems are downstream.

If u wanna browse, search and download AI agent skills, use openskills.space

Are there good techniques for testing / benchmarking skills effectiveness?

All these sites just look exactly like claude code skills doc.

Tank: We're supposed to start with these operation programs first. That's major boring shit. Let's do something a little more fun. How about... combat training.

Neo: Ju jitsu? I'm gonna learn Ju jitsu.

[Tank winks and loads the program] Neo: Holy shit!

KYS

one good thing vercel did, was indexing skills.md under a site skills.sh - and yes there are now 100s of these sites, but I like the speedy/lite approach from vercel's DX, despite me not liking vercel a whole lot

Is it just me, or do skills seem enormously similar to MCP?

…including, apparently, the clueless enthusiasm for people to “share” skills.

MCP is also perfectly fine when you run your own MCP locally. It’s bad when you install some arbitrary MCP from some random person. It fails when you have too many installed.

Same for skills.

It’s only a matter of time (maybe it already exists?) until someone makes a “package manager” for skills that has all of the stupid of MCP.

It's hilarious that after all those years of resistance to technical writing and formal specification engineers and programmers have suddenly been reduced to nothing more than technical writers and specification designers. Funny that I somehow don't foresee technical writing pay bumps happening as a consequence of this sudden surge in importance.

Sounds like a bunch of bullshit to me. A simple markdown file with whatever and a directory will do the same. This is just packaging, selling and marketing.

[dead]

[dead]

[dead]

[dead]