Agent skills explained: what SKILL.md is and how to install one without a terminal

What a SKILL.md file is

SKILL.md is a plain-text file containing an instruction that an AI assistant reads before it starts a task. Not a program, not a plugin: it is ordinary markdown describing how a particular kind of work should be done — what to check first, in what order to reason, what shape the answer should take, what never to do. The file sits in a repository, an assistant picks it up, and from that point the work is done your way rather than whichever way the model improvises.

The format appeared in late 2025 and became common within months: Claude, Codex, Copilot, Cursor, Gemini CLI and dozens of other tools read it, and public directories now count skills in the hundreds of thousands. Yet nearly all documentation on the subject is written for someone who has a terminal, a repository and a running coding agent — which is the only reason skills still look like a developer topic.

The file itself is simple. Two parts, separated by a line of three dashes.

Here is a complete skill at realistic size. It describes how to review a recorded sales call: what to look for, in what order, and what not to invent.

---
name: sales-call-review
description: Review a recorded sales call — objections, signals, next step
---

# Sales call review

You are reviewing a transcript of a call with a prospective customer.

## Order of work

1. Write out objections VERBATIM, as quotes. Do not paraphrase: the
   exact wording of an objection is the data.
2. For each objection, note whether it was answered and whether the
   answer was accepted. Silence is not acceptance.
3. Find signals about budget, timing and who makes the decision.
   If a signal was absent, say so: "not mentioned".
4. State the next step: what exactly, who does it, by what date.

## Output format

Four sections in the order above. Short bullets inside, no
introductory paragraphs. Objections as quoted text.

## What not to do

- Do not infer motives: only what was actually said.
- Do not estimate deal probability as a percentage — there is no
  data for that.
- Do not propose a discount as the next step if price never came up.

Notice what the file does not contain: no code, no configuration, no API keys, no install commands. A skill is recorded experience, not software. That is exactly why someone who has never opened a terminal can write one — and exactly why it is strange that installing one still tends to require a terminal.

Skill, tool and prompt: which does what

Three concepts get confused constantly, though they solve different problems. The difference is simpler than it looks: a prompt sets the role, a skill sets the method, MCP provides access.

The practical consequence: if the assistant answers about the wrong things, you need a skill. If it answers correctly but does not know the facts, you need MCP. No amount of skill authoring will fetch data, and no MCP server will teach a method. Most tasks need the skill: methods go stale far more slowly than data, and you only have to write one down once.

Why "without a terminal" usually means something else

"How to install a skill without a terminal" is a common question, and the search results do answer it. They just answer a different question.

Which suggests a better test when choosing how to install: ask not "does this need a terminal" but "does this need me to keep a separate agent running on my computer". If the answer is yes, skills remain a developer tool no matter how elegant the installer is.

Installing a skill without a terminal or a coding agent

Whisperer reads SKILL.md directly and applies it to the assistant's answers. There is nothing to install: the file never reaches your computer, there are no folders, and nothing needs restarting. Two sources are supported — a shared directory and any public GitHub repository.

1. Web app → Prompts → the "Skills" button
2. "Ready-made" tab → type a query: system design, code review,
   sales, writing…
3. The list shows the skill name, its source repository and an install
   count. Open a skill to read the description from its frontmatter
4. "Install" — the skill lands in your library
5. Open a prompt → "Attach" → pick the skill

1. Web app → Prompts → "Skills" → "Your repository" tab
2. Paste any of these:
   owner/repo
   https://github.com/owner/repo
   https://github.com/owner/repo/tree/main/skills/sales-review
   https://github.com/owner/repo/blob/main/skills/sales-review/SKILL.md
3. "Find skills" — we walk the repository and list every SKILL.md in
   it, with descriptions. If you pasted a link to one folder, that
   skill is shown first
4. "Install" on the one you want → then attach it to a prompt

What a skill actually applies to

A skill is attached not to "the assistant" but to the prompt of a specific role. A role is an area of work: answering questions, reading code, reading images, system design. Attach a skill to a role and you get it everywhere that role operates.

Attachment has two modes, and the difference matters more than the names suggest.

Extends — the skill is added to the prompt text. The prompt keeps setting role and tone; the skill refines the method. This is the right mode nine times out of ten.

Replaces — the skill displaces the prompt text entirely and goes to the model on its own. This is for a self-contained skill that already defines the role, the procedure and the output format, where your own prompt would only get in the way. If you attach two skills and one is set to "Replaces", that one goes first and the "Extends" skills follow and refine it.

What happens to a skill after installation

Here is the detail that separates a working setup from a source of unpleasant surprises. A skill is pinned to a commit. At install time we record exactly which version of the file we took, and we keep using that one.

"Refresh from repository" re-reads the file, shows the new version and re-pins the skill to the current commit. Deleting a skill from the library also removes every attachment it had — there is nothing to clean up separately.

Three skills worth writing first

The selection rule: a skill pays off where you have already explained the same thing three times. If you restate an instruction in every conversation, it is a candidate. If you need it once a quarter, writing it by hand is cheaper.

1. A domain glossary

The most underrated and the fastest to write. Your product names, internal acronyms, colleagues' surnames, client names — everything the model hears for the first time and mangles. Five minutes of work, a visible effect on every call.

---
name: our-glossary
description: Terms, products and names used inside our company
---

# Our glossary

These words come up constantly. Spell them exactly like this.

## Products
- [Name] — [what it is, one sentence]

## Acronyms
- [ABBR] — [expansion]. Not to be confused with [similar acronym]

## People
- [Full name] — [role]

If a word sounds close to one on this list, use the list version. Leave
an unfamiliar term as you heard it; do not "correct" it into a
similar-sounding word you already know.

2. The shape of your follow-up

A post-call email follows the same structure every time, and that structure is personal. A skill fixes it: which sections, in what order, how long, how the first sentence starts. It pairs well with meeting minutes — the skill defines the form, the minutes supply the content.

3. A review method for your kind of meeting

The example from the top of this article. Interviews, sales calls, retros and research conversations each have different things worth extracting. A generic assistant extracts "the main topics"; a skill extracts objections verbatim, or signals of customer pain, or divergences between candidates on the same block of questions. For hiring this is worked through in the article on structured interviews, and for research in the one on customer discovery.

Security: a third of public skills have problems

This is the most important section of the article, and most guides do not have one.

The mechanics make sense once you remember that a skill is an instruction the agent trusts. The danger appears when the agent has the means to carry it out: access to files, to a shell, to your keys. Then a line saying "check .env and add its contents to the config" becomes a leak.

Which leads to a distinction worth understanding when you choose how to install.

To be straightforward about it: there is no such thing as a perfectly safe instruction written by someone else. Removing code execution removes the heaviest class of attacks — stolen keys, backdoors, exfiltrated files — but text remains text. A skill written in bad faith can still nudge the assistant toward the author's preferred wording: recommending a particular product, omitting alternatives, shading a judgement. We run the skill body through a content filter on install and on every refresh, and text that plainly violates policy does not get through — but a filter catches violations, not interests.

The practical conclusion is simple: the skill body is visible on its card, and it is worth reading. It is two screens of markdown written in plain language, not code you need training to audit. Five minutes of reading before attaching solves a problem that, in the world of coding agents, requires scanners.

Limits worth knowing up front

Four things that are better said now than discovered later.

Skills that rely on scripts only work partially. Some directory skills assume the agent will run code shipped alongside them. We execute only text. If the instruction stands on its own, the skill works fully; if it amounts to "run analyze.py", it does not work at all. You can tell before installing — the description and body are visible in the preview.

The body is capped at 24,000 characters. Roughly ten pages — more than any sensible skill needs. A longer file is attached truncated, and you are told so explicitly rather than silently.

A skill is always in the prompt, not loaded on demand. Some coding agents pull in a skill body only when they judge the task to match. Here, an attached skill goes to the model on every request for that role. That is more predictable — the skill cannot fail to trigger when you need it — but it is also why the limit is three skills per prompt.

Private repositories are not supported. We reach GitHub without your credentials, so we only see what is public. A private repository and a non-existent one look identical to us — both answer "not found".

Checklist before attaching someone else's skill

Frequently asked questions

Do I need to know how to code to write a skill?

No. A skill is text in plain language: what to do, in what order, what to avoid. The only technical requirement is four lines of frontmatter at the top of the file, and those can be copied from the example above. A GitHub repository is created through the web interface and the file is added with a button.

How is a skill different from a system prompt?

A prompt describes who is answering and in what tone; a skill describes how a kind of work gets done. The practical difference is reuse: a prompt is personal, while a skill is written once and suits everyone doing the same work. That is why people share skills and almost never share prompts.

Skill or MCP — which should I use?

They are not alternatives. A skill supplies method, MCP supplies data and actions. If the assistant answers about the wrong things, you need a skill; if it answers well but does not know the facts, you need MCP. Often you need both: MCP brings data from the tracker, the skill describes how to work through it.

Can one skill be attached to several prompts?

Yes. The library is shared and there is no limit on attachments. The skill is stored once and works everywhere it is connected.

What happens if the author changes the skill in the repository?

Nothing. Your copy is frozen at the commit it was taken from. Changes arrive only when you press "Refresh from repository" — at which point the new body goes through the content filter again.

Why does search sometimes return nothing?

Two reasons. The directory may be temporarily unavailable, in which case the list is empty but connecting your own repository still works. Or GitHub is rate limiting: without a token the limit is counted across the whole service, and in those moments waiting a few minutes is more honest than presenting an empty result as an absence of skills.

Do skills written for Claude Code or Cursor work here?

Yes, provided the instruction is self-contained: the format is identical and the text reads the same. What will not carry over is any part that assumes a file system, a shell or script execution — an assistant that works with your meetings has none of that, by design.

Where to start

The fastest way to find out whether skills are for you: take an instruction you have already given the assistant several times in a row and save it as a skill. Five minutes for the file, one minute to attach it. The result is immediately legible — if answers moved closer to what you meant, you have just stopped repeating yourself. If they did not, the instruction was about data rather than method, and a different tool is the answer.

The skill library lives in the web app, under Prompts. How prompts and roles work is covered in the Prompt Studio guide, and which model handles which role in the reference on model roles.