Claude Code Skill設計10パターン｜確実に発火するdescriptionと運用テンプレ
Claude CodeのSkillは、使い始めるとかなり強力です。ただ、最初に詰まるのはだいたい同じです。Skillを書いたのに発火しない。 私もZYL0 Blog用に投資記事、クリエイター記事、技術記事のSkillを分けたとき、最初のdescriptionが抽象的すぎて、思った場面で呼ばれませんでした。
この記事では、実際にこのブログで使っているSkill運用を題材に、確実に呼ばれるdescriptionとSKILL.mdの設計パターンをまとめます。2026年5月時点のClaude Codeでは、Skill、Subagent、Hook、MCP、Plan modeがそれぞれ役割を持つので、Skillだけに詰め込みすぎないのも大事です。
Version note: 2026年5月時点のClaude Codeドキュメントと、ZYL0 BlogのローカルSkill運用を前提にしています。CLIや設定仕様は変わる可能性があります。
| テーマ | 学べること |
|---|
| description | Skillが発火しやすい書き方 |
| trigger phrases | ユーザー文に反応する具体語の置き方 |
| scope | Skillに入れること、入れないこと |
| validation | Skillが呼ばれるか確認する方法 |
| operations | 複数Skillをブログ運用で使い分ける型 |
最初にかなり大事なところです。Skillのdescriptionは自己紹介ではなく、ルーティング条件です。
悪い例：
description: Write blog posts for my site.
これだと、どんな記事でも呼ばれるのか、どんな形式で出すのか、どこに保存するのかが曖昧です。
良い例：
description: >
Write bilingual Japanese + English technical blog posts for ZYL0 Blog.
Use when the user asks for a developer tutorial, coding guide,
architecture deep-dive, MCP article, Claude Code article, or implementation notes.
Output a Nuxt Content Markdown file under content/blogs/ with ::lang-block sections.
私の感覚では、descriptionには最低でも以下を入れた方が安定します。
| 要素 | 例 |
|---|
| 対象読者 | programmers, creators, investors |
| 入力トリガー | "記事を書いて", "Claude Code", "MCP", "投資テーマ" |
| 出力形式 | bilingual Markdown, Nuxt Content, ::lang-block |
| 保存先 | content/blogs/ |
| 除外条件 | code blocks avoided, no inline HTML など |
Skillは「便利なメモ」ではなく、CodexやClaudeにとってのルーティングテーブルだと考えると設計しやすいです。
発火率を上げる一番簡単な方法は、ユーザーが入力しそうな言葉をdescriptionにそのまま入れることです。
description: >
Use whenever the user asks to write a technical article,
developer tutorial, coding guide, tool comparison,
architecture deep-dive, or says "記事にして", "実装してみた",
"Claude Code", "MCP", "API integration", or "AI engineering".
私は最初、「technical content」とだけ書いていました。でも実際の依頼文は「MCPの記事」「Claude Codeの使い方」「技術記事にして」のようにもっと具体的です。Skill側がその言葉を知らないと、別の一般Skillに流れやすい。
ここはSEOに似ています。きれいな抽象語より、読者が検索窓に入れる生々しい語の方が効きます。
ZYL0 Blogでは、少なくとも3種類の記事があります。
| Skill | 読者 | 文体 |
|---|
| zyl0-blog-writer | 投資家、CVC、個人投資家 | データ、シナリオ、銘柄 |
| zyl0-creator-blog-writer | クリエイター、SNS発信者 | 共感、体験、CTA |
| zyl0-tech-blog-writer | エンジニア、開発者 | 実装、コード、落とし穴 |
1つのSkillに全部入れると、毎回トーンがぶれます。特にブログ運用では、読者ごとに「良い記事」の条件が違う。投資記事はシナリオ分析が必要ですが、クリエイター記事では長い銘柄表は邪魔です。技術記事ではコードとバージョン注記が必要ですが、一般向け記事では重くなりすぎる。
Skillは、機能別より判断基準別に分けた方が使いやすいと感じています。
ブログ記事生成Skillなら、frontmatterの順番まで固定した方が事故が減ります。
---
title: '日本語タイトル | English Title'
description: '日本語の概要。80〜160字。'
date: '22nd May 2026'
image: '/blogs-img/blog-slug.png'
alt: '画像説明'
ogImage: '/blogs-img/blog-slug.png'
tags: ['テック解説', 'AI活用']
tagsEn: ['Tech Deep Dive', 'AI Tools']
published: true
---
ここを「適切なfrontmatter」と書くだけだと、フィールド名や順番が毎回揺れます。Nuxt Contentではfrontmatterの欠落がビルドやカード表示に効くので、Skillに具体例を入れておく価値があります。
私のおすすめは、正しい例を1つだけ置くことです。複数パターンを置くと、逆に迷います。
Nuxt ContentではMDCが便利ですが、記事本文に好き勝手なコンポーネントを入れると、保守が重くなります。ZYL0 Blogでは、記事本文の基本は
::lang-block
だけにしています。
::lang-block{lang="ja"}
# 日本語タイトル
本文...
::
---
::lang-block{lang="en"}
# English Title
Body...
::
Skillに「MDCを使ってよい」とだけ書くと、勝手なカードやalert風コンポーネントを使う可能性があります。だから「
::lang-block
のみ可」「インラインHTML禁止」まで書きます。
この手の制約は、モデルを縛るためというより、未来の自分を助けるためです。半年後に記事を直すとき、本文がシンプルなMarkdownに近いほど楽です。
Skillに全部を必須扱いで書くと、出力が重くなります。逆に、何も必須にしないと品質が揺れます。私は以下のように分けています。
| 種類 | 例 |
|---|
| 必須 | 日英完全ブロック、frontmatter、免責文、タグ |
| 強く推奨 | TL;DR表、シナリオ分析、次号案 |
| 任意 | 筆者の経験談、追加図表、比較表 |
技術記事では、コードブロックと落とし穴は必須に近い。一方、クリエイター記事ではコードは原則なし。ここをSkillごとに分けると、出力がかなり安定します。
意外と効くのが、悪い例です。
# Bad
description: Write high quality content.
# Good
description: >
Use when the user asks for a bilingual ZYL0 Blog post about investing,
geopolitics, energy, AI infrastructure, semiconductors, space,
robotics, or startup themes.
悪い例を置くと、どの抽象度がダメなのかが伝わりやすい。人間のチーム運用でも同じですが、良い例だけだと境界が見えにくいです。
私がDD品質基準をチームで標準化したときも、「良いメモ」だけでなく「投資委員会で刺されるメモ」を見せた方が早かった。Skill設計もかなり似ています。
技術記事や投資記事では、古い情報が一番危険です。だからSkillには、執筆前に公式ドキュメント、リリースノート、GitHub、ニュース、決算資料を確認する、と書きます。
ただし、情報源を固定しすぎると、新しい一次情報を取り逃がします。私ならこう書きます。
Before writing, verify current facts with 5-8 searches:
- official documentation or release notes
- GitHub changelog/issues where relevant
- recent market/news sources
- primary company or university announcements where available
Do not include uncertain API specs or code examples.
重要なのは、「調べること」より「不確かなものを書かないこと」です。技術記事で動かないコードを置くと、読者の信頼は一気に落ちます。
記事生成Skillでも、最後に何を確認するかを書いておくと便利です。
After writing:
- check frontmatter fields
- confirm both lang-blocks close with ::
- run npm run lint when code files changed
- run npm run build before commit
もちろん、記事だけなら毎回lint/buildが必要とは限りません。ただ、ブログ全体を変更する運用では「最後に何を見るか」がSkill内にあるだけで事故が減ります。私の場合、公開前の確認漏れがかなり減りました。
最後に、Skillに入れすぎないための整理です。
| 仕組み | 得意なこと | 入れない方がよいこと |
|---|
| Skill | 手順、文体、出力形式、制約 | 長時間の独立調査 |
| Subagent | 独立した調査、レビュー、分担 | 常時必要な文体ルール |
| Hook | 実行前後の強制チェック | 判断が必要な執筆方針 |
| MCP | 外部データへの接続 | ローカル記事フォーマット |
Skillは「この作業はどうやるか」を教える場所です。Subagentは「この調査を分けてやってきて」と頼む場所。Hookは事故防止。MCPは外部状態への接続。ここを混ぜると、どの層で何を直すべきか分からなくなります。
私の現在の運用では、Skillが記事の型を決め、リサーチは必要に応じて別に走らせ、最後はlint/buildで確認します。地味ですが、これが一番壊れにくいです。
Skill設計で一番大事なのは、魔法のプロンプトを作ることではありません。毎回の判断を減らすことです。
すぐ使えるテンプレを最後に置きます。
---
name: project-specific-writer
description: >
Use when the user asks for [task type] for [project/audience],
especially with phrases like [trigger phrase 1], [trigger phrase 2],
or [trigger phrase 3].
Produce [exact output format] at [path], following [key constraints].
---
この型に沿って、対象読者、トリガー語、出力形式、保存先、禁止事項を入れる。それだけでSkillの発火率はかなり上がります。最初から完璧に作る必要はありません。むしろ、発火しなかった依頼文を1つずつdescriptionへ戻していく方が、実戦では強いです。
- MCPで社内ナレッジを接続する最短ルート：DDメモ、ポートフォリオ情報、過去提案をClaude Codeに接続する30分実装。
- Hooksで事故らない開発環境を作る：PreToolUse、PostToolUse、Stopを使った実用テンプレ集。
- Subagentを使ったブログリサーチ分業：投資、技術、読者ニーズを並列調査して1本の記事に統合する運用。
本記事は技術情報の共有を目的としたもので、特定サービスの利用を推奨するものではありません。執筆過程で生成AIの支援を活用しています。本サイトの注意事項はこちらをご覧ください。
10 Claude Code Skill Design Patterns: Descriptions and Templates That Trigger Reliably
Claude Code Skills become powerful very quickly once you start using them. But the first failure mode is almost always the same: you wrote a Skill, and it does not trigger when you expect it to. I hit this when I split ZYL0 Blog into investment, creator, and technical writing Skills. My first descriptions were too abstract, so the right Skill did not always get selected.
This article uses my actual blog workflow as the reference point and turns it into design patterns for descriptions and SKILL.md files. As of May 2026, Claude Code has Skills, subagents, hooks, MCP, and Plan mode, each with a distinct role. One practical rule: do not stuff all of them into a Skill.
Version note: This is based on Claude Code documentation and my local ZYL0 Blog Skill workflow as of May 2026. CLI and configuration behavior can change.
| Topic | What you'll learn |
|---|
| description | How to make Skills easier to route to |
| trigger phrases | How to include the words users actually type |
| scope | What belongs in a Skill and what does not |
| validation | How to check whether the Skill is being selected |
| operations | How to run multiple Skills in one publishing workflow |
This is the core point. A Skill description is not a bio. It is routing metadata.
Bad:
description: Write blog posts for my site.
This does not say which posts, what format, where to save them, or when the Skill should beat other Skills.
Better:
description: >
Write bilingual Japanese + English technical blog posts for ZYL0 Blog.
Use when the user asks for a developer tutorial, coding guide,
architecture deep-dive, MCP article, Claude Code article, or implementation notes.
Output a Nuxt Content Markdown file under content/blogs/ with ::lang-block sections.
At minimum, I want the description to contain:
| Element | Example |
|---|
| Audience | programmers, creators, investors |
| Input triggers | "write an article", "Claude Code", "MCP", "investment theme" |
| Output format | bilingual Markdown, Nuxt Content, ::lang-block |
| Destination | content/blogs/ |
| Exclusions | code blocks avoided, no inline HTML, etc. |
Think of a Skill as a routing table, not a helpful note. That mental model makes design easier.
The easiest way to improve trigger reliability is to include realistic user phrases.
description: >
Use whenever the user asks to write a technical article,
developer tutorial, coding guide, tool comparison,
architecture deep-dive, or says "記事にして", "実装してみた",
"Claude Code", "MCP", "API integration", or "AI engineering".
My first version said only "technical content." But users do not speak that way. They say "an MCP article," "how to use Claude Code," or "turn this into a technical post." If the Skill does not name those phrases, the request can route elsewhere.
This is close to SEO. Elegant abstract language is less useful than the messy words people actually type.
ZYL0 Blog has at least three article types.
| Skill | Audience | Style |
|---|
| zyl0-blog-writer | investors, CVCs, individual investors | data, scenarios, stocks |
| zyl0-creator-blog-writer | creators and social publishers | empathy, experience, CTA |
| zyl0-tech-blog-writer | engineers and developers | implementation, code, gotchas |
If one Skill handles all three, tone drifts. For blog work, "good article" means different things for different readers. Investment posts need scenarios. Creator posts need empathy and action. Technical posts need code, versions, and failure modes.
I have found Skills more useful when split by decision criteria, not merely by function.
For a blog-writing Skill, frontmatter should be specified concretely.
---
title: '日本語タイトル | English Title'
description: 'Japanese description, 80-160 characters.'
date: '22nd May 2026'
image: '/blogs-img/blog-slug.png'
alt: 'Image description'
ogImage: '/blogs-img/blog-slug.png'
tags: ['テック解説', 'AI活用']
tagsEn: ['Tech Deep Dive', 'AI Tools']
published: true
---
If you write "use appropriate frontmatter," fields and order drift. In Nuxt Content, missing metadata can affect builds and cards, so examples are worth the space.
My preference is to include one correct example. Multiple examples often create unnecessary choice.
MDC is useful in Nuxt Content, but if articles start using random components, maintenance gets heavier. In ZYL0 Blog, the body should generally use only
::lang-block
.
::lang-block{lang="ja"}
# 日本語タイトル
本文...
::
---
::lang-block{lang="en"}
# English Title
Body...
::
If a Skill merely says "MDC is allowed," it may introduce custom cards or alerts. I prefer to write "
::lang-block
only" and "no inline HTML."
This is less about constraining the model and more about helping future maintenance. Six months later, simple Markdown is easier to edit.
If everything is mandatory, outputs become bloated. If nothing is mandatory, quality drifts. I separate elements like this:
| Type | Examples |
|---|
| Required | complete JP/EN blocks, frontmatter, disclaimer, tags |
| Strongly recommended | TL;DR table, scenario analysis, Next Issue Ideas |
| Optional | personal story, extra diagrams, comparison tables |
For technical posts, code and gotchas are close to required. For creator posts, code blocks are usually noise. Encoding that per Skill stabilizes output.
Bad examples help more than expected.
# Bad
description: Write high quality content.
# Good
description: >
Use when the user asks for a bilingual ZYL0 Blog post about investing,
geopolitics, energy, AI infrastructure, semiconductors, space,
robotics, or startup themes.
A bad example shows the boundary. Good examples alone can make the abstraction level hard to infer.
When I standardized diligence quality at a prior CVC, showing "good memos" helped. Showing "memos that get challenged in investment committee" helped faster. Skill design has the same flavor.
For technical and investment writing, stale information is the biggest risk. The Skill should say to verify official documentation, release notes, GitHub, news, company announcements, and primary sources where relevant.
But do not freeze the source list too tightly. I would write:
Before writing, verify current facts with 5-8 searches:
- official documentation or release notes
- GitHub changelog/issues where relevant
- recent market/news sources
- primary company or university announcements where available
Do not include uncertain API specs or code examples.
The key is not "do research" as a ritual. The key is "do not publish uncertain claims." In technical writing, one broken code sample can cost a lot of trust.
Even a writing Skill should say what to check at the end.
After writing:
- check frontmatter fields
- confirm both lang-blocks close with ::
- run npm run lint when code files changed
- run npm run build before commit
Not every article-only change needs lint and build, but for a blog workflow that often touches code, having the exit checks inside the Skill reduces misses. It has reduced my own publishing mistakes.
The final pattern is about avoiding overload.
| Mechanism | Best at | Avoid putting here |
|---|
| Skill | workflow, tone, output format, constraints | long independent investigations |
| Subagent | isolated research, review, parallel work | always-on writing style |
| Hook | forced checks before/after actions | judgment-heavy editorial decisions |
| MCP | external data and system access | local article formatting rules |
A Skill tells the agent how this work should be done. A subagent is for "go investigate this separately." A hook is for accident prevention. MCP is for external state. Mixing them makes it hard to know where a problem should be fixed.
My current workflow is simple: Skills define article shape, research runs separately as needed, and lint/build verify the repo before publishing. It is not flashy, but it is resilient.
The most important part of Skill design is not writing a magical prompt. It is removing repeated decisions.
Here is the template I would start from:
---
name: project-specific-writer
description: >
Use when the user asks for [task type] for [project/audience],
especially with phrases like [trigger phrase 1], [trigger phrase 2],
or [trigger phrase 3].
Produce [exact output format] at [path], following [key constraints].
---
Add the audience, trigger phrases, output format, destination, and prohibited patterns. That alone improves trigger reliability. You do not need perfection on day one. In practice, the strongest Skill descriptions are built by taking the requests that failed to trigger and folding those phrases back into the description.
- The shortest path to connecting internal knowledge over MCP — DD memos, portfolio data, and old proposals inside Claude Code.
- A zero-accident dev environment with Hooks — practical PreToolUse, PostToolUse, and Stop templates.
- Blog research with Subagents — splitting investment, technical, and reader-needs research before merging one article.
This article is intended as technical knowledge sharing and is not a recommendation of any specific service. Generative AI was used to assist drafting. See our disclaimer for full details.
