[CCA-F] Introduction to Agent Skills

What are skills?

1.skills vs CLAUDE.md vs slash commands

-skills : on demand로 쓰인다. 클로드가 필요하다고 판단하면 자동적으로 쓰인다.
-CLAUDE.md : 이 안의 내용은 전부 context에 로드된다.
-slash commands : 명시적으로 업로드한다.

어느 특정 순간에 반복적으로 명령하는 구문들이 있다? skill로 만들어라.

Creating your first skill

적절한 frontmatter structure를 갖추시오.
skill 은 SKILL.md가 있는 디렉토리에서 로드된다. 그리고 frontmatter는 이렇게 구성된다.

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

...
..
.

이렇게 필수 요소로 name과 description이 들어간다. 그 아래의 ...에 이제 skill의 내용이 좀 더 들어가게 되는 것이다. 처음에 클로드는 name과 description만 업로드한다. name은 skill간의 구분, description은 이제 클로드가 이 스킬을 쓸지 말지 판단할 때 사용된다.

그리고 혹시 name이 겹치는 스킬들이 있을 수 있다. 이에 대한 우선순위는 다음과 같다.
Enterprise > personal > project > plugins
만약 자기가 호출하고 싶은 스킬이 있는데 기대와 다르게 동작한다면, 어디에서 불러왔는지 부터 확인하라. 이래서 이름은 잘 지어야 하고, 설명은 구분이 가능하게 적어야 한다.

Configuration and multi-file skills

1.skill에서 사용 가능한 metadata properties들이 있는데, 적절히 사용해라.

2.skill 사용시 허용된 도구(tool)로 하여금 skill이 할 수 있는 일을 제한하라.

name:
description:
allowed-tools : Read, Grep, Bash
model: sonnet

이렇게 skill에게 네가 할 수 있는 일은 여기까지고 네가 쓸 수 있는 모델은 이거야 라고 정해줄 수 있다.

3.description 잘 써서 클로드가 스킬 검색할 때 적절하게 검색 잘 될 수 있도록 해라.

4.다른 disclosure를 사용해서 스킬을 500줄 이내로 유지하자!

(편집주 : 원래 이렇게 안 쓰여 있습니다.)

disclosure를 어떻게 번역할 지 좀 애매해서 - 굉장히 현학적인 뜻이 나왔단 말이다! - 예시를 보니까
여기서는 skill의 내용을 잘 펼쳐서 별도의 구조를 갖춘 파일들에 저장해, 원본 SKILL.md 파일을 500줄 이내로 유지하는게 포인트로 보인다.

open standard에는 이런 구조를 사용하라고 권장한다.
-scripts : 실행 가능한 도구. 실행 할 때 말고 결과를 도출할 때만 토큰을 쓴다.
-references : 추가로 참고할 만한 내용이 있다면 여기 쓴다.
-assets: 우리가 코딩할 때 assets에 넣고 쓰는 이미지나 템플릿 같은 데이터들.

script의 경우 실행 환경 검증, 일정하게 데이터 변환할 때, script의 코드를 명시적으로 수행하는게 클로드가 생성한 코드를 수행하는 것 보다 더 나을 경우에 사용한다고 한다.

Skills vs other Claude Code features

1.skills vs CLAUDE.md, subagents, hooks, MCP servers

-CLAUDE.md : 늘 적용되는 사항들 쓰기
-subagents : isolate from main conversation. 일을 분리시켜 알아서 하게 만들때.
-hooks : 어떤 이벤트가 발생할 때 동작하는 것들. event-driven automate operations.
-MCP servers : 외부 툴과 연결할 때 사용.

그렇다면 skills는 어떨 때 사용할까?
-task-specific agent
-특정 상황에서만 쓰이는 지식
-좀 더 자세하게 설명하려고 할 때 따로 떼서 저장

2.적절하게 커스텀한 기능 사용하기.

3.여러 기능들을 엮어 상호보완적으로 사용하기

Sharing skills

1.skill sharing 방법 : git repo, plugin, marketplace, enterprise 단계에서 관리되는 설정에 의한 전파 등

Enterprise의 경우 'strictKnownMarketplaces'와 같은 설정으로 어디서 스킬을 공유받을지 설정할 수 있다.

"strictKnownMarketplaces": [
  {
    "source": "github",
    "repo": "acme-corp/approved-plugins"
  },
  {
    "source": "npm",
    "package": "@acme-corp/compliance-plugins"
  }
]

2.subagent는 main agent와 달리 자동으로 skill을 볼 수 없다.

원래는 subagent들이 skill을 쓰게 하세요~ 였는데 이유가 더 중요해서 제목을 이렇게 지었다.
custom agent의 forntmatyter skills field에 명시적으로 사용 가능한 스킬을 명시해줘야 한다.
그리고 Built-in-agents(Explorer, Plan, Verify)도 마찬가지다.
.claude/agent에 정의되어있는 agent들만 skills를 명시적으로 썼을 때 사용 가능하다.

---
name: frontend-security-accessibility-reviewer
description: "Use this agent when you need to review frontend code for accessibility..."
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
model: sonnet
color: blue
skills: accessibility-audit, performance-check
---

subagent에게 일 시킬 때 깨끗한 context로 시작하게 되는데, main과 다르게 시작할 때 skill을 context에 모두 로드한다. on demand가 아니다.
skill을 subagent에게 쓰게 할 경우 일을 명시적으로, 일일이 프롬프트 치고 싶지 않고 위임할 때 좋다.

Troubleshooting skills

1. skill validator : structural issue 잡기

이 경우 uv라는 것을 사용하면 편리하다고 되어있었다.

2. skill triggering과 loading시 자주 일어나는 문제

파일 권한 문제 때문에 plugin이나 script등이 실행 되지 않을 때, chmod +x고려하기

3. skill priority 문제 해결하기

이건 skills priority가 어떻게 결정되는지 곰곰히 생각해보면 해결된다.

4. runtime error에 대해 디버깅하기 : 의존성, 권한, 경로 확인하기

claude --debug로 왜 에러가 났는지 디버깅해볼 수 있다.