Published SolidJS Best Practices as a Skill on skills.sh

I use skills.sh regularly. Being able to manage knowledge passed to agents as skills is convenient, and I’ve been gradually adding them for personal and team use.

As I started writing more SolidJS, I wanted a skill for it. Things like reactivity breaking when you destructure props, or knowing when to use <For> instead of .map() — I was getting tired of providing that context every time.

So I built one with Claude Code and published it on skills.sh. Here’s a note on the process for future reference.

Creating the Skill

Launch /skill-creator and answer its questions to get a draft.

/skill-creator

What is the skill for, when should it trigger, what do you expect in the output. Answer these three and it produces a SKILL.md draft. Way faster than writing from scratch.

Fix the description yourself

Once you have the draft, you should always revise the description by hand. Its precision directly determines trigger accuracy.

# Too vague — rarely triggers
description: SolidJS help

# What I actually use
description: SolidJS のコードを書いたりレビューするためのベストプラクティス。
  createSignal, createEffect, createMemo, createStore, createResource,
  createContext, Show, For, Switch, SolidJS, solid-js が出てきたら使う。
  React パターンを Solid に変換する質問や、コンポーネントが更新されない
  バグのデバッグにも使う。

Don’t just list keywords — describe the situations where it should be used, and it will pick up on implicit scenarios too.

Keep SKILL.md under 500 lines

SKILL.md is always loaded into context. If it gets too long, it crowds out other work. I structured it so that details go into references/ and are only referenced when needed.

## When using SolidStart

See [`references/solidstart.md`](references/solidstart.md) for details.

Verify the difference with tests

/skill-creator has a feature that runs with-skill and without-skill in parallel for comparison.

I prepared three test cases.

When I actually ran them, the without-skill version handled <For> and createResource reasonably well. The differences showed up in the following areas.

In the code review, the with-skill version detected the reactivity-breaking issue from destructuring props in arguments as Critical. The without-skill version missed it.

In the Todo creation, the with-skill version suggested createStore + produce, while the without-skill version stopped at createSignal<Todo[]>.

In async fetching, the with-skill version suggested a Suspense and ErrorBoundary combination. The without-skill version used manual users.loading checks.

The props destructuring bug is something Claude already knows about. But the behavior changes depending on whether the skill includes the judgment criterion to always flag it during review. Writing skills to reliably catch framework-specific pitfalls — that’s how I’ve come to think about it.

Publishing on skills.sh

Create a repository that conforms to the skills.sh open standard and you can publish. Same structure as vercel-labs/agent-skills.

Repository structure

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

Prepare the frontmatter

Before publishing, add license, metadata.author, and metadata.version.

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

The name rules are subtly strict. Lowercase alphanumeric and hyphens only. Must match the directory name. No leading or trailing hyphens, no consecutive hyphens.

Validate before pushing

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

This checks frontmatter format and naming rules all at once. I recommend running it before pushing.

Write a README and you’re done

# agent-skills

## Skills

### solidjs-best-practices

SolidJS のコードを書いたりレビューするためのベストプラクティス集。

## インストール

npx skills add mktbsh/agent-skills

Push to GitHub and it’s published. That’s all there is to it.

Wrap-up

Description precision and the process of verifying differences through testing determine skill quality. Cut corners on either, and you end up with a skill that exists but you can’t tell if it’s actually working.

The more you pack in specific know-how — the kind where not knowing it gets you stuck — rather than generic knowledge, the more effective the skill becomes.