Five checks before you copy an open source skill folder

What a skills repository ships

A skills repository on GitHub holds one folder per skill, and the folder holds a SKILL.md. The file opens with frontmatter, name and description. The rest is the instruction an agent reads once the skill loads. Beside it, a maintainer may keep what those instructions point at: a checklist in references/, a script in scripts/, a template. Nothing compiles. What you copy is source you can read before an agent runs it.

The rest of the tree says what a skill expects to find. addyosmani/agent-skills keeps commands/, agents/, references/ and evals/ beside skills/. anthropics/skills keeps spec/, the format's own text, and template/. elastic/agent-skills keeps plugins/ and scripts/. In all three, the skills are one part of a kit, which matters the moment you lift one folder out.

Three layouts, and what each predicts

addyosmani/agent-skills is flat: 25 folders under skills/, each named after the skill inside it, plus a README mapping nine slash commands onto a lifecycle. The folder for code-review-and-quality holds one file. That shape is the easiest to copy. The README also states the cost: "A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory." Those checklists stayed one level up, an issue the README tracks as #361 rather than leaving to the copier. It also ships npx skills add addyosmani/agent-skills --list, which shows the catalogue before anything lands.

anthropics/skills is self-contained by design. Its README calls each skill "self-contained in its own folder with a SKILL.md file". The pdf folder shows the shape: SKILL.md, forms.md, reference.md, a scripts/ directory and a LICENSE.txt. Copy that folder and the reference material comes with it. The README also marks docx, pdf, pptx and xlsx as not open source, each with its own LICENSE.txt inside. Read that file before the terms surprise whoever approves the copy.

elastic/agent-skills is nested: a skill lives at skills/elasticsearch/elasticsearch-cluster-health/SKILL.md, with a category folder in between. Its frontmatter carries more than the two required fields. metadata holds an author and a version, and compatibility names the versions the skill covers and one it does not, Elastic Cloud Serverless, "where cluster, shard, and allocation APIs are managed internally". The README opens with a Technical Preview notice. A nested layout is a test of whether your copy command knows the path.

Five checks, in the order a copy goes wrong

The folder name and the name line have to agree. The folder's last segment is the skill's name. Elastic's folder reads elasticsearch-cluster-health and so does its frontmatter. That match holds across a repo or fails across it.

Read the description as a trigger list. The frontmatter of `code-review-and-quality` says "Use before merging any change". Then "Use when reviewing code written by yourself, another agent, or a human", then two more moments. Four trigger phrases in one line. That line is what the loader matches a task against, and a description of what the skill is leaves it nothing to match.

Look at what the body assumes. A SKILL.md that sends the agent to references/checklist.md works when the file travels with the folder. It fails quietly when it does not, which is the addyosmani caveat seen from your side of the copy. That README grants use under MIT and says nothing about scope: "MIT - use these skills in your projects, teams, and tools." anthropics/skills is the one that states a scope up front, in a Disclaimer: "These skills are provided for demonstration and educational purposes only." Elastic's compatibility field does that job where a tool can read it.

Weigh the largest body, since all of it loads when the skill fires. The code-review-and-quality folder holds a single file of about 21 kilobytes. Then read the install section, as a description of what you will not get.

The three ways a copy goes wrong in your repository

The first is the folder and the frontmatter name disagreeing, and a machine catches it. The reference manifest lists "a skills folder with no SKILL.md, or a SKILL.md whose frontmatter name: is not the skill name" as an error (kortix.yaml reference). kortix validate exits 1 on it. The grant uses the folder's name, so rename the folder to match the name.

The second is a description that never fires. An agent loads a skill when a task matches the description. A line written in another team's vocabulary can sit unloaded for months while everyone assumes it works. Rewrite the trigger words for the way your tasks arrive, then leave the steps alone.

The third is a body that outgrew its references. With a per-skill install the checklist stayed at the repository root. The agent reads the body, finds no checklist, and fills the gap with invention. A SKILL.md past a few hundred lines is usually two skills. The second half belongs in references/, which loads only when the agent asks.

Where the folder goes, and the line that loads it

Put the folder at skills/<name>/ and change nothing else on the way in. An edit made during a copy is an edit nobody reviewed. Then register it and grant it in kortix.yaml. A registered skill reaches no agent until a grant names it, and an omitted skills key grants nothing (kortix.yaml reference). A folder from another repository is a dependency, and keeping it honest takes a pin: the record of source, path and hash that skills in your repository shows in full.

What lands is then a change request. Session work reaches main through a change request. Merge is default-deny for agents. A copied folder that arrives that way carries a reviewer's name and a history you can roll back. Kortix's own project works this way. Open source. Read it, fork it, audit it.

What to borrow, and what to write yourself

Borrow for jobs that are the same at any company: reviewing a diff, reading a PDF, drafting release notes. Write your own when the skill carries a decision only your company can make. Approval thresholds, queue names, escalation order, the wording of a reply to a customer. A borrowed skill that names another company's policy is a liability with good formatting.