What are agent skills? (from a README)

This is a repo for sharing agent skills other people at [work] might want to copy and expand on.

The bar for adding something here is meant to be low. If you think anyone else might find your skill useful, share it. It doesn’t have to be polished or work on anyone else’s machine. Half-finished is fine; just say so in the file. If it turns out to be widely useful, we can clean it up later.

Repo-specific skills belong in a .claude/skills directory in that repo. Skills that aren’t company-specific can live in public repos and get a link here instead:

• session-history: search and summarize past Claude Code, Codex, and opencode sessions
• browser-interact: drive a browser with Playwright scripts for frontend work
• shellout: hand a self-contained task to a cheaper model through codex exec

See RFD 576 for the company policy on LLM use.

What is a skill?

If you ask your coding agent to do something, and it takes a little trial and error, and you think you might want to do it again, it’s often worth telling it to write down what it did so it doesn’t have to figure it out again next time. That’s a skill.

Skills are just piles of prompts (Markdown) and scripts (any language your computer can run). Don’t get too hung up on the prompt part: a lot of the time, the bulk of the info will be in scripts, and the skill is mostly there to tell the model to use the script, which you could just as well tell it yourself.

When skills are installed, they aren’t loaded into your agent sessions in full by default like a CLAUDE.md is. Only the name and description from the Markdown frontmatter are loaded up front, so the agent can decide when to use each skill. If you have a skill called search-matrix, and the description says it’s for searching Matrix, you don’t have to type /search-matrix yourself: if you tell Claude to search Matrix for X, it will usually do the right thing.

Why write a skill?

There are a few broad reasons skills can be useful and it’s clarifying to think about the difference, though it’s not always obvious which category a given skill is in. Sometimes seemingly private knowledge turns out to be something smarter models can infer from other available info.

Giving the model knowledge it couldn’t have on its own

Some of the most useful skills are just telling the model things it needs to know in order to get work done, like a new employee needs onboarding no matter how experienced they are. Private facts like where some piece of information lives, how internal systems happen to be set up, the URL for the colo rack, etc. Another category of thing it can’t know: preferences — yours or the team’s — that reasonable people could disagree on. Think “I like code written in a dense functional style” as opposed to “make sure the code compiles.”

Making the agent faster (and saving tokens)

Sometimes the model is perfectly capable of figuring out how to do something from scratch, but it just takes a while. Once you’ve done it, there’s no need to wait next time. The RFD and meeting search skills are an example of this. Using a CLI is perfectly within agents’ abilities, but there might be details about logging in or how to use particular commands that take some trial and error to figure out.

Working around lack of model capability

The other kind of skill teaches the model how to do something the right way because it can’t figure it out on its own. Things like instructions on how to sound less bizarre in writing.

These are things that improve on their own (to some extent) with better models. This isn’t just about models improving over time: even at one time, there are things an expensive model can do out of the box that a cheaper model can’t. So if you want to use the cheaper model, you can try to make up for its lack of smarts with a detailed prompt.

How to use

Many of these skills are meant as examples to follow rather than something to pull off the shelf and use directly. They might have their author’s username or project names hard-coded into them, so you’ll usually want your agent to adapt them to your needs.¹

Note this repo is not set up as a Claude plugin. That always seemed like a lot of machinery, plus it’s Claude-specific and we want this to work with other harnesses. Here are some ways to use these skills:

• Give your agent a link to the repo and tell it to set up a skill for you
• Clone the repo and symlink or copy the skills you want into ~/.claude/skills/ for Claude Code or ~/.agents/skills/ for Codex (or a project’s .claude/skills/ or .agents/skills/ to use them only there). Copy if you’re going to adapt a skill, so your edits stay out of your checkout of this repo.
• Tell your agent to read a skill’s SKILL.md and follow it, if you just want to try it once without installing it.

Skills that read internal data (RFDs, meeting transcripts, Matrix) should only be used from an agent signed in to one of our enterprise accounts, not a personal subscription, since whatever the agent reads goes to the model provider under that account. As a backstop, the skills here tell the agent to check this itself or ask you; if you write a new one that reads internal data, do the same. But ultimately the responsibility to do things right lies with you, the user.

Risks

Skills can include scripts that run on your machine, so skim what you install and have agents review it for risks.² There are a number of ways a skill in this repo might be imperfect:

• It may work well at the time it’s posted, but then get out of date as the systems it’s concerned with change.
• It might make assumptions about sandboxing that were true for the author but aren’t for you.
• It may have been built to work around limitations in model capability at a given time. If current models no longer have these limitations, the instructions in the skill may be too narrow and therefore counterproductive. For any skill that’s more than a few months old, it’s always worth considering whether current models can just do that thing out of the box.

If you find a skill that’s stale or no longer needed, fix it or delete it.

Contributing

Just push your skills. Put each skill in its own top-level directory named after the skill. If you are changing a skill someone else wrote, you might want to make a PR and discuss it. Otherwise, edit files at will.

If you want to do the next person a favor, mark hard-coded values like your username or project name with CUSTOMIZE and a few words on what goes there, so they’re easy to grep for. This is optional.