SolidJS 베스트 프랙티스를 skills.sh에서 스킬로 공개했다

평소에 skills.sh를 자주 쓰고 있다. 에이전트에 넘기는 지식을 스킬로 관리할 수 있는 게 편리해서, 개인용·팀용으로 조금씩 늘려왔다.

SolidJS를 작성할 일이 많아지면서 스킬이 필요해졌다. props의 destructuring으로 reactivity가 깨지는 문제라든가, .map() 대신 <For>를 써야 하는 상황이라든가, 매번 컨텍스트로 보충 설명하는 게 번거로워지고 있었다.

겸사겸사 Claude Code로 만들어서 그대로 skills.sh에 공개했다. 공개 절차의 비망록으로 남겨둔다.

스킬 만들기

/skill-creator를 실행하고 질문에 답하면 드래프트를 작성해준다.

/skill-creator

어떤 목적의 스킬인지, 어떤 상황에서 트리거하고 싶은지, 출력에 기대하는 것은 무엇인지. 이 세 가지에 답하면 SKILL.md 드래프트가 나온다. 처음부터 직접 작성하는 것보다 압도적으로 빠르다.

description만은 직접 수정한다

드래프트가 나오면 description만큼은 반드시 직접 손을 대는 게 좋다. 여기의 정확도가 곧 트리거 정확도가 된다.

# 대충 쓰면 거의 트리거되지 않는다
description: SolidJS 도움말

# 실제로 사용 중인 것
description: SolidJS 코드를 작성하거나 리뷰하기 위한 베스트 프랙티스.
  createSignal, createEffect, createMemo, createStore, createResource,
  createContext, Show, For, Switch, SolidJS, solid-js가 등장하면 사용한다.
  React 패턴을 Solid로 변환하는 질문이나, 컴포넌트가 갱신되지 않는
  버그 디버깅에도 사용한다.

키워드 나열뿐만 아니라 어떤 상황에서 쓰는지까지 적어두면 암묵적인 시나리오에서도 잡아준다.

SKILL.md는 500행 이내로 유지한다

SKILL.md는 항상 컨텍스트에 로드된다. 너무 길어지면 다른 작업을 압박하기 때문에, 세부 사항은 references/에 분리하고 필요할 때만 참조하는 구성으로 했다.

## SolidStart를 사용하는 경우

자세한 내용은 [`references/solidstart.md`](references/solidstart.md) 참조.

테스트로 차이를 확인한다

/skill-creator에는 with-skill과 without-skill을 병렬 실행해서 비교하는 기능이 있다.

테스트 케이스는 3개를 준비했다.

실제로 돌려보니, 스킬 없이도 <For>나 createResource는 어느 정도 사용하고 있었다. 차이가 나타난 건 다음 부분이었다.

코드 리뷰에서는 스킬이 있을 때 props를 인수에서 destructure하면 reactivity가 깨지는 문제를 Critical로 감지했다. 스킬이 없을 때는 놓쳤다.

Todo 작성에서는 스킬이 있을 때 createStore + produce를 제안한 반면, 스킬이 없을 때는 createSignal<Todo[]>로 끝났다.

비동기 취득에서는 스킬이 있을 때 Suspense와 ErrorBoundary 조합을 제안했다. 스킬이 없을 때는 users.loading의 수동 체크였다.

props의 destructuring 버그는 Claude가 원래 알고 있는 지식이다. 다만, 리뷰에서 반드시 지적한다는 판단 기준이 스킬에 있느냐 없느냐로 동작이 달라진다. 프레임워크 고유의 함정을 확실히 잡아내기 위해 스킬을 작성한다는 게 나름의 정리가 됐다.

skills.sh에 공개하기

skills.sh의 오픈 표준에 준거한 리포지토리를 만들면 공개할 수 있다. vercel-labs/agent-skills와 같은 구성이다.

리포지토리 구성

agent-skills/
├── LICENSE
├── README.md
└── skills/
    └── solidjs-best-practices/
        ├── SKILL.md
        └── references/
            └── solidstart.md

프론트매터를 정리한다

공개 전에 license, metadata.author, metadata.version을 추가한다.

---
name: solidjs-best-practices
description: ...
license: MIT
metadata:
  author: mktbsh
  version: "1.0.0"
---

name 규칙은 은근히 세세하다. 소문자 영숫자와 하이픈만 허용. 디렉터리 이름과 일치시킨다. 앞뒤에 하이픈 불가, 연속 하이픈도 불가.

밸리데이션을 통과시킨 후 push한다

npx skills-ref validate ./skills/solidjs-best-practices

frontmatter 형식이나 네이밍 규칙을 한꺼번에 체크해준다. 이걸 통과시킨 후 push하는 걸 추천한다.

README를 작성하면 완성

# agent-skills

## Skills

### solidjs-best-practices

SolidJS 코드를 작성하거나 리뷰하기 위한 베스트 프랙티스 모음.

## 설치

npx skills add mktbsh/agent-skills

GitHub에 push하면 공개 완료. 이것만으로 끝난다.

정리

description의 정확도와 테스트로 차이를 확인하는 프로세스가 스킬의 품질을 결정한다. 둘 다 대충하면 스킬을 만들었는데 효과가 있는 건지 잘 모르겠다는 상태가 된다.

범용적인 지식보다, 이걸 모르면 막힌다는 구체적인 노하우를 담을수록 스킬은 효과를 발휘한다.