write-skill
Create or improve a Claude Code Agent Skill (SKILL.md). Use when the user asks to capture a workflow as a skill, create a reusable skill, or turn something we just did together into a skill.
- License 许可
- MIT
- 所属仓库
- gurdiga/dotfiles
- 最近更新
- 2026-10-10
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- write-skill
- description
- Create or improve a Claude Code Agent Skill (SKILL.md). Use when the user asks to capture a workflow as a skill, create a reusable skill, or turn something we just did together into a skill.
02 资源文件 2
- 参考文档examples/sample.transcript.json1.4 KB
- 脚本scripts/transcribe_media.mjs17.9 KB
03 SKILL.md 正文
Writing a Skill
Storage
- Personal (all projects):
~/.claude/skills/<skill-name>/SKILL.md - Project-level:
.claude/skills/<skill-name>/SKILL.md
Structure
Every skill is a directory containing at minimum a SKILL.md:
skill-name/
├── SKILL.md # required
├── scripts/ # optional: executable helpers
├── references/ # optional: reference docs loaded on demand
└── assets/ # optional: templates, static files
SKILL.md format
---
name: skill-name
description: What it does and when to trigger it. Be specific about
trigger phrases — Claude tends to undertrigger, so be a little pushy:
"Use this whenever the user mentions X, Y, or asks about Z."
---
# Skill Title
Instructions in imperative form. Explain the *why* behind each step,
not just the what — Claude is smart and works better with reasoning
than with rigid rules.
Frontmatter reference
All fields are optional. description is strongly recommended.
| Field | Description |
|---|---|
name |
Display name. Defaults to directory name. Lowercase, hyphens only, max 64 chars. |
description |
When to use the skill. Claude's primary trigger signal. |
when_to_use |
Extra trigger context appended to description in the skill listing. |
argument-hint |
Autocomplete hint, e.g. [issue-number] or [filename] [format]. |
arguments |
Named positional args for $name substitution (space-separated or YAML list). |
disable-model-invocation |
true = only user can invoke. Use for side-effectful workflows (deploy, commit, export). |
user-invocable |
false = hide from / menu. Use for background knowledge, not commands. |
allowed-tools |
Tools pre-approved without prompting, e.g. Bash(git *) Read. |
model |
Model override while this skill is active. |
effort |
Effort level override: low, medium, high, xhigh, max. |
context |
Set to fork to run in an isolated subagent context. |
agent |
Subagent type when context: fork: Explore, Plan, general-purpose, or a custom agent name. |
hooks |
Hooks scoped to this skill's lifecycle. |
paths |
Glob patterns limiting when the skill auto-activates (e.g. src/**/*.ts). |
Invocation control
By default both user and Claude can invoke a skill. Two fields restrict this:
disable-model-invocation: true— only the user can invoke (description hidden from Claude). Use for workflows with side effects: deploy, commit, send messages, export.user-invocable: false— only Claude can invoke (hidden from/menu). Use for background knowledge that isn't actionable as a command.
Dynamic context injection
A SKILL.md can run shell commands at load time and substitute their output, so Claude sees live data rather than the command itself. Two forms:
- Inline — a bang followed by the command in single backticks, dropped into a line of prose or under a heading.
- Block — a fence opened with three backticks immediately followed by
!(no language tag). Every line inside runs as one shell script, and the combined output replaces the block.
This section describes both forms in prose rather than showing them, on purpose. The loader scans for those literal sequences anywhere in the file — inside fenced code blocks and inside double-backtick escapes alike — so any example of the syntax executes as if it were real. An earlier version of this file documented the block form by example and aborted its own load; the inline example silently ran git diff HEAD on every load and pasted the result here.
A command that exits nonzero aborts the entire skill load, so guard anything that can fail — cmd 2>/dev/null || echo "fallback".
String substitutions
| Variable | Value |
|---|---|
$ARGUMENTS |
All arguments passed at invocation |
$ARGUMENTS[N] or $N |
Argument by 0-based index |
$name |
Named argument declared in arguments frontmatter |
${CLAUDE_SESSION_ID} |
Current session ID |
${CLAUDE_EFFORT} |
Current effort level |
${CLAUDE_SKILL_DIR} |
Directory containing this SKILL.md — use to reference bundled scripts portably |
Example using ${CLAUDE_SKILL_DIR}:
python3 ${CLAUDE_SKILL_DIR}/scripts/analyze.py
Writing guidelines
Description is the triggering mechanism — it's the only part always in context. Make it unambiguous about when to activate.
Body should be under 500 lines. If it grows beyond that, move reference material into references/ files and link to them.
Prefer explaining reasoning over issuing mandates with MUST/NEVER. A model that understands why does better than one following rigid rules.
Bundled scripts are useful for deterministic, repetitive steps. They execute via Bash; only their output enters context, not their code. Reference them via ${CLAUDE_SKILL_DIR}/scripts/your-script.sh so the path resolves correctly at any install level.
Generalize from the specific case that prompted the skill. The skill will be used in many different contexts, so avoid over-fitting to the example at hand.
After writing
Tell the user where the skill was saved. Edits to existing skills take effect immediately (Claude Code watches skill directories for changes). New skill directories require restarting Claude Code to be picked up.
04 同仓库更多 Skills
ssh-controlmaster
Use a persistent SSH connection via ControlMaster when running multiple commands against the same remote host, to avoid repeated authentication overhead. Use when about to run several ssh commands in a row against one host.
reflect
Analyze recent session transcripts for the current project and suggest CLAUDE.md improvements. Invoke manually once a month or after a significant stretch of work.
grill-me
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
git-message-style
Vlad's personal conventions for writing commit messages and PR descriptions — subject shape, body rules, vocabulary, and PR body structure. Use when writing a commit message or a PR description in one of Vlad's personal repos (not a team repo with its own convention).
gem-security-update
Fix Dependabot security alerts for Ruby gems. Use when the user shares a GitHub Dependabot URL, asks to fix gem vulnerabilities, or mentions a gem CVE needing a version bump.
export-conversation
Export the current conversation to a markdown file. Use this whenever the user asks to "export", "save", or "write" the conversation to a file, or says something like "export this conversation to X.md".