SolidJSのベストプラクティスをskills.shでスキルとして公開した

普段から skills.sh をよく使っている。エージェントに渡す知識をスキルとして管理できるのが便利で、自分用・チーム用に少しずつ増やしてきた。

SolidJS を書く機会が増えて、スキルが欲しくなった。props の destructuring で reactivity が壊れるやつとか、.map() じゃなく <For> を使うべき場面とか、毎回コンテキストで補足するのが面倒になっていた。

せっかくなので Claude Code で作って、そのまま skills.sh で公開した。公開手順の備忘録として残しておく。

スキルを作る

/skill-creator を起動してヒアリングに答えていくと、ドラフトを書いてくれる。

/skill-creator

何のためのスキルか、どんなときにトリガーしたいか、出力に期待することは何か。この3つに答えると 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 の精度と、テストで差を確認するプロセスがスキルの品質を決める。どちらも手を抜くと、スキルを作ったけど効いているのかよくわからないという状態になる。

汎用的な知識より、これを知らないと詰まるという具体的なノウハウを詰め込むほど、スキルは効いてくる。