기본 콘텐츠로 건너뛰기

Agent Skills: One SKILL.md for Claude Code, Cursor, Copilot

Summary: Agent Skills is the open SKILL.md format that Claude Code, Cursor and GitHub Copilot all read, so one folder of instructions can follow you between tools. The catch is that each tool looks in different folders and adds its own frontmatter fields. This guide shows the one folder location all three read today, a minimal skill that passes the official validator, and which extra fields break portability.

Everything here was checked today against the Agent Skills specification at agentskills.io, Anthropic's announcement, the anthropics/skills repository, and the skills pages in the Claude Code, Cursor, VS Code and GitHub Copilot docs. I also installed the reference validator (skills-ref 0.1.0) from the agentskills GitHub repository and ran it against a valid skill and five deliberately broken ones; the real output is in the screenshots at the end of this post. I did not run the skill inside every paid product, so where a doc is the only evidence I say so.

What Agent Skills is, in one paragraph

A skill is a folder with a SKILL.md file in it. The file starts with YAML frontmatter (at minimum a name and a description) followed by plain Markdown instructions. The folder can also hold scripts/, references/ and assets/. Agents load skills in three steps: at startup they read only the name and description of every skill, when a task matches a description they read the full SKILL.md, and only then do they open the bundled files they need. That is why a good description matters more than a long body.

Anthropic built the format while working on Claude Code, published it as an open standard in December 2025, and on October 22, 2026 donated it to the Agentic AI Foundation (AAIF) under the Linux Foundation, the same home it gave the Model Context Protocol. The announcement says more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated it. The specification now lives at agentskills.io, while github.com/anthropics/skills is Anthropic's own collection of example skills (its README says so at the top).

Step 1: Put the skill where every tool can find it

This is the part most tutorials skip. Each product documents its own folders:

  • Claude Code reads project skills from .claude/skills/<name>/SKILL.md and personal skills from ~/.claude/skills/. Its skills page lists only .claude locations (plus enterprise, nested, --add-dir and plugin locations); I found no mention of .agents/skills there.
  • Cursor reads .agents/skills/ and .cursor/skills/ in the project and ~/.agents/skills/ and ~/.cursor/skills/ for your user, and "for compatibility" also loads .claude/skills/, .codex/skills/ and their home-folder versions.
  • GitHub Copilot supports project skills in .github/skills, .claude/skills or .agents/skills, and personal skills in ~/.copilot/skills or ~/.agents/skills. VS Code's Local sessions also read .claude/skills/ and .agents/skills/.

Put those lists side by side and one project folder is on all of them: .claude/skills/. The newer vendor-neutral .agents/skills/ works for Cursor, Copilot and Codex, but according to the docs above it would not be picked up by Claude Code. So for a repository shared by people on different tools, today's safest layout is:

your-repo/
└── .claude/
    └── skills/
        └── release-notes/
            ├── SKILL.md
            └── scripts/
                └── changes.sh

If your team uses only Cursor and Copilot, .agents/skills/ is the cleaner, tool-neutral choice. For personal skills there is no single shared home folder across all three, so you would keep a copy (or, in Claude Code's case, a symlink, which its docs explicitly support) in each tool's location.

Step 2: Write a SKILL.md that passes the spec

The specification allows only six frontmatter fields: name and description (required), plus license, compatibility, metadata and the experimental allowed-tools. Here is the minimal skill I validated:

---
name: release-notes
description: Drafts release notes from merged pull requests using the team template. Use when the user asks for release notes, a changelog, or a summary of what shipped.
license: MIT
metadata:
  author: example
  version: "1.0"
---
# Release notes
1. Run scripts/changes.sh

The rules for name: 1 to 64 characters, lowercase letters, digits and hyphens only, no leading or trailing hyphen, no double hyphen, and it must match the folder name. The description can be up to 1,024 characters and should say both what the skill does and when to use it, with the words a user would actually type. "Helps with PDFs" is the spec's own example of a poor description.

For the body, the spec recommends step-by-step instructions, input and output examples and edge cases, keeping SKILL.md under 500 lines (roughly under 5,000 tokens) and moving long material into references/. Reference files with relative paths from the skill root, and keep them one level deep.

Step 3: Validate it before you commit

The agentskills project publishes a reference library called skills-ref. I installed it into a Python virtual environment straight from the GitHub repository (the package is in the skills-ref subfolder of agentskills/agentskills) and ran skills-ref validate ./release-notes. It printed "Valid skill: release-notes". Then I broke things on purpose. These are the exact failures it reported:

  • Folder notes-dir with name: release-notes: "Directory name 'notes-dir' must match skill name 'release-notes'".
  • name: Release-Notes2: "must be lowercase".
  • name: double--hyphen: "cannot contain consecutive hyphens".
  • No description: "Missing required field in frontmatter: description".
  • A 1,100-character description: "Description exceeds 1024 character limit".
  • A skill using disable-model-invocation and paths: "Unexpected fields in frontmatter".

That last result is the interesting one, because both of those fields are documented and useful in Claude Code and Cursor. The tool also has a to-prompt command that prints the <available_skills> block an agent would see, which is a quick way to read your description the way the model reads it.

Step 4: Decide how much vendor-specific frontmatter to use

Each product extends the six standard fields. Claude Code adds disable-model-invocation, user-invocable, context: fork, paths, model, hooks and more, and it even treats name as optional (it defaults to the folder name). Cursor adds paths, disable-model-invocation, icon and color. VS Code adds argument-hint, user-invocable, disable-model-invocation and an experimental context: fork.

My rule of thumb: keep shared skills to the six spec fields so the validator stays green, and only add vendor fields in a skill that you know is used by one tool. disable-model-invocation: true is the most widely shared extra (Claude Code, Cursor and VS Code all document it as "only run when I type /name"), so it is the one I would accept if you need manual-only skills, knowing the strict validator will flag it.

Where each tool reads skills

Tool Project folders Personal folders Extra frontmatter (examples) Access notes from the docs
Claude Code .claude/skills/ (also nested and --add-dir) ~/.claude/skills/ disable-model-invocation, user-invocable, context, paths, model Custom skills on claude.ai are separate uploads (Pro, Max, Ultra, Team, Enterprise with code execution); skills do not sync between claude.ai, the API and Claude Code
Cursor .agents/skills/, .cursor/skills/ (also reads .claude/skills/, .codex/skills/) ~/.agents/skills/, ~/.cursor/skills/ (also ~/.claude/skills/, ~/.codex/skills/) paths, disable-model-invocation, icon, color Only ~/.cursor/skills/ can sync to Cloud Agents; automations need the skill in the repo
GitHub Copilot (incl. VS Code) .github/skills, .claude/skills, .agents/skills ~/.copilot/skills, ~/.agents/skills argument-hint, user-invocable, disable-model-invocation, context (experimental) Copilot CLI on all Copilot plans; cloud agent on paid plans

Editor's note

Good fit: teams whose members use different coding agents and keep repeating the same multi-step chores (release notes, test runs, deploy checklists, review rules). One skill in .claude/skills/ replaces three copies of the same prompt.

Not a fit: always-on coding style rules. VS Code's docs draw this line clearly: custom instructions such as AGENTS.md are always applied, skills load on demand. Put formatting rules in instructions, workflows in skills.

Gotchas I hit or confirmed:

  • A skill silently not loading in VS Code is often the name: its docs say slashes, colons, dots or prefixes like myorg:skill in name make the skill "silently fail to load". Plugins add the prefix for you.
  • Folder and name mismatch is the most common validator failure, and Claude Code hides it because it falls back to the folder name.
  • Personal skills do not follow you into the cloud. Claude Code's cloud sessions and Cursor's automations do not read your home folder; commit the skill to the repository instead.
  • Skills can contain scripts. Both Anthropic and VS Code tell you to review every bundled file before installing a skill from someone else.

FAQ

Is anthropics/skills the standard?

No. Its README says it is Anthropic's implementation and examples for Claude; the standard itself is at agentskills.io and is now maintained under the AAIF. The repository is still the best place to read real, production-sized skills such as the docx, pdf, pptx and xlsx ones, which it says are Apache 2.0 licensed.

Can I use a skill from the repository directly in Copilot or Cursor?

Yes, as long as you copy the whole folder (not just SKILL.md) into a supported location. GitHub's docs name anthropics/skills and github/awesome-copilot as sources and mention gh skill for installing skills from repositories. Cursor's docs say repository imports go through a plugin marketplace rather than being pulled in automatically.

Do I need to pay to use Agent Skills?

The format and the validator are free and open. Whether the agent that reads them costs money depends on the product: GitHub's docs list Copilot CLI on all Copilot plans and the cloud agent on paid plans, and Claude's docs list custom skill uploads on claude.ai for paid plans with code execution enabled.

Related reading on this blog: Claude Code Errors Fixed: Login, PATH, 429 and Usage Limits if Claude Code itself will not start, GitHub Copilot Pricing: Free, Pro, Pro+ and Max Credits to see which Copilot plan you need, and Promptfoo Tutorial: Test Your LLM Prompts Before You Ship for testing the instructions you put in a skill.

Start with one boring, repeated task, put it in .claude/skills/, run the validator, and let every agent on your team share it.

See the official screenshots at the end of this post. Image credit: my own screenshots of the public Agent Skills specification (agentskills.io), Cursor Docs and VS Code Docs, plus my own terminal output from skills-ref.

Last verified: 2026-11-11
Sources: Agent Skills specification, Agent Skills overview, Anthropic: Donating Agent Skills to the Agentic AI Foundation, anthropics/skills, skills-ref reference library, Claude Code: Skills, Claude Docs: Agent Skills overview, Cursor Docs: Agent Skills, VS Code: Use Agent Skills, GitHub Docs: Agent skills.

Uploaded Image Uploaded Image Uploaded Image Uploaded Image

댓글

이 블로그의 인기 게시물

브루(Vrew) 요금제 정리: 무료 200크레딧으로 어디까지 쓸 수 있나

요약: 영상 자막 편집기 브루(Vrew)는 2026년 4월 22일부터 기능별 사용량 대신 '통합 크레딧' 하나로 요금을 매겨요. 무료 플랜은 매달 200크레딧이 들어오는데, 음성 분석(자동 자막)만 쓰면 최대 200분 분량이라 짧은 영상 몇 편은 충분하지만, 영상 초반의 Vrew 마크를 지우려면 유료 플랜이 필요해요. 이 글은 브루 공식 가격 페이지와 고객센터 공지를 2026년 10월 23일에 다시 확인해, 크레딧 계산법과 플랜 고르는 기준을 정리했어요. 목차 브루 요금 구조: 통합 크레딧이란 1크레딧으로 할 수 있는 일 무료 플랜으로 되는 것과 안 되는 것 유료 플랜 4종 비교표 월 구독·연 구독·기간 이용권, 무엇이 이득일까 상황별 추천: 학생·직장인·유튜버 크레딧이 모자랄 때: 사용 기록 지우개 업그레이드·환불 전에 알아둘 규칙 운영자 메모, 자주 묻는 질문 1. 브루 요금 구조: 통합 크레딧이란 예전 브루는 플랜마다 음성 분석 몇 분, AI 목소리 몇 자, 번역 몇 자처럼 기능별 한도를 따로 줬어요. 그런데 보이저엑스(브루 운영사)가 실제 이용 데이터를 보니 한두 가지 기능만 집중해서 쓰는 사람이 훨씬 많았다고 해요. 그래서 2026년 4월 22일 업데이트부터는 플랜마다 정해진 크레딧을 받고, 어떤 기능에 쓸지는 내가 정하는 방식으로 바뀌었어요. 플랜별 매달 지급량은 Free 200 · Light 2,000 · Standard 10,000 · Business 12,000크레딧 이에요. 공식 공지에 따르면 무료 사용자는 매달 1일에, 유료 사용자는 매월 결제일에 충전되고, 남은 크레딧은 다음 달로 넘어가지 않아요. 바뀐 뒤 무엇이 좋아졌나 공지에 나온 예시가 이해하기 쉬워요. Standard 플랜에서 AI 목소리만 쓰면 예전에는 최대 50만 자였지만, 지금은 1만 크레딧을 모두 AI 목소리에 몰아 쓸 수 있어 최대 100만 자가 돼요. 반대로 여러 기능을 골고루 쓰는 사람은 크레딧이 기능끼리 ...

에이닷 전화 vs 익시오: 통화 녹음·AI 요약, 내 통신사·폰에 맞는 앱 고르기

요약: 통화 녹음과 AI 요약을 쓰고 싶다면 먼저 내 통신사와 휴대폰 종류부터 확인해야 해요. LG유플러스 고객은 무료 앱 익시오, SKT 고객은 에이닷 전화가 가장 기능이 많고, 다른 통신사의 아이폰 사용자는 iOS에 들어 있는 기본 통화 녹음·전사 기능이 현실적인 선택이에요. 이 글은 2026-10-30에 SKT·LG유플러스·Apple 공식 페이지와 도움말을 직접 확인해 세 가지를 비교했어요. 왜 '앱 기능'보다 '내 조건'을 먼저 봐야 할까요 통화 요약 앱 비교 글을 보면 기능 목록부터 나열하는 경우가 많아요. 그런데 실제로 써 보려는 사람에게 가장 먼저 걸리는 건 기능이 아니라 이용 조건 이에요. 익시오는 LG유플러스 고객 전용이고, 에이닷 전화는 누구나 설치할 수 있지만 통역콜·baro 같은 기능은 SKT 고객에게만 열려 있어요. 아이폰은 운영체제 구조상 앱이 통화를 마음대로 녹음하기 어려워서, 통신사 앱이 안 되면 iOS 기본 기능에 기대야 해요. 그래서 이 글은 "어떤 앱이 제일 좋은가"보다 "내 통신사·내 폰에서 무엇을 쓸 수 있나" 순서로 정리했어요. 기능 차이는 그다음이에요. 한눈에 비교: 에이닷 전화 vs 익시오 vs 아이폰 기본 통화 녹음 구분 에이닷 전화 (SKT) 익시오 ixi-O (LG유플러스) 아이폰 기본 통화 녹음 (Apple) 누가 쓸 수 있나 통신사 구분 없이 앱 설치 가능. 단, 통역콜·baro·그룹통화 발신 등은 SKT 고객 전용 U+ 모바일 고객. 타 통신사, 만 14세 미만, 선불요금제 고객은 제한 (공식 사이트 FAQ상 알뜰폰 중 KB리브엠은 예외) 지원 국가·언어의 iPhone 사용자. 1명과 통화할 때만 녹음 가능 지원 OS·기기 Android 10 이상, iOS 16 이상 iOS 17 이상 iPhone 12 이상 / Android...

타입캐스트 vs 클로바더빙: 수익 나는 채널에 쓸 때 무료·유료 조건 비교

요약 타입캐스트와 클로바더빙은 둘 다 글만 입력하면 한국어 AI 목소리를 만들어 주는 서비스지만, 무료로 쓸 수 있는 범위가 꽤 다릅니다. 클로바더빙 무료는 매달 15,000자까지 쓸 수 있는 대신 수익이 생기는 채널에는 쓸 수 없고, 타입캐스트 무료는 처음에 주는 약 5분 분량의 다운로드로 끝나는 체험판에 가깝습니다. 광고 수익이 붙은 유튜브나 쇼핑몰 영상에 넣을 목소리라면 처음부터 유료 플랜 조건을 보고 고르는 편이 안전합니다. 왜 이 두 서비스를 같이 비교하나 쇼츠 내레이션, 수업 자료 더빙, 상품 소개 영상처럼 "내 목소리 대신 AI 목소리"가 필요할 때 한국 사용자들이 가장 많이 찾는 곳이 네오사피엔스의 타입캐스트 와 네이버의 클로바더빙 입니다. 기능 소개만 보면 비슷해 보이지만, 실제로 문제가 되는 건 음질보다 "이 목소리를 내 채널에 써도 되나" 입니다. 그래서 이 글은 기능 나열보다 무료 사용 범위, 출처 표기 의무, 유료 플랜 가격과 다운로드 한도를 중심으로 정리했습니다. 모든 수치는 2026년 10월 25일에 두 서비스의 공식 요금 페이지와 고객센터 도움말에서 직접 다시 확인한 내용입니다. 한눈에 보는 비교표 항목 타입캐스트 무료 타입캐스트 베이직 클로바더빙 Free 클로바더빙 Standard 월 요금 0원 9,900원 (연간 결제 시 10% 할인) 0원 19,900원 (네이버 클라우드 플랫폼에서 결제) 무료·포함 사용량 음성 생성·재생 무제한, 다운로드는 최초 3,000크레딧(약 5분) 1회 지급 월 30,000크레딧(약 60분) 월 15,000자, 다운로드 월 20회, 프로젝트 누적 5개 (매월 1일 갱신) 월 30,000자, 다운로드 월 40회, 프로젝트 누적 20개 쓸 수 있...