跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

writing-skills

Guides creation or update of a `SKILL.md`: chooses the right frontmatter fields (`description` vs `when_to_use`, `argument-hint`, `model`, `effort`, `allowed-tools`, `paths`, `disable-model-invocation`, etc.), runs two pressure tests, and follows the approval flow before writing.

gsarig · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add gsarig/skills --skill writing-skills

技能说明


name: writing-skills description: "Guides creation or update of a SKILL.md: chooses the right frontmatter fields (description vs when_to_use, argument-hint, model, effort, allowed-tools, paths, disable-model-invocation, etc.), runs two pressure tests, and follows the approval flow before writing." when_to_use: "Use when asked to write, create, or update a skill (SKILL.md file). Follow all steps in order; do not shortcut based on this description." effort: xhigh

Steps

1. Clarify the trigger condition

Before writing anything, establish: in what situation should this skill activate? The answer must be a specific, observable event (something the user says or does), not a description of what the skill will accomplish. This becomes the when_to_use field, not description.

If the trigger is vague ("when it seems useful"), ask for a concrete example before proceeding.

2. Determine where the skill lives

ScopeLocation
Global (applies across all projects)~/.claude/skills/<name>/SKILL.md
Project-specific.claude/skills/<name>/SKILL.md in the project root

Ask if not obvious from context.

3. Pick the frontmatter fields

Every skill uses name, description, and when_to_use. Go through the rest of the field list and include only what genuinely applies; omit the rest.

FieldInclude when
descriptionAlways. One sentence on what the skill produces or does; outcome-focused, not a walkthrough of the steps.
when_to_useAlways. Trigger phrases, example user requests, and the anti-shortcut suffix: Follow all steps in order; do not shortcut based on this description.
argument-hintThe skill accepts an argument (URL, file path, vault name). Format as "[what it accepts]".
model: sonnet (or haiku)The skill is a mechanical workflow that does not need the session model's full capability; pinning a cheaper model saves usage. Omit for high-judgment skills (review, interview, design) so they inherit the session model. Never pin a model to force quality upward: a pin caps the skill when the session runs a stronger tier (e.g. Fable).
effort: highThe skill requires high-judgment reasoning and benefits from deeper thinking.
allowed-toolsThe skill runs repetitive commands that would otherwise prompt (e.g. Bash(git *) Bash(gh *) Read). Additive, not restrictive.
pathsThe skill naturally scopes to specific files expressible as a glob (e.g. **/*.config.json). Auto-triggers the skill when editing those files.
disable-model-invocation: trueThe skill has side effects that should require deliberate user invocation (posting to a live site, deploying, deleting).
user-invocable: falseThe skill is pure background knowledge; the user never types /skill-name.
licenseThe skill is open-source or shareable. Common values: MIT, Apache-2.0.
metadataCustom key-value pairs for distribution: author, version, mcp-server, category, tags, documentation, support. Useful when publishing publicly.

4. Draft the skill

Use this structure. Omit any field that does not apply.

---
name: <skill-name>
description: "<one-sentence outcome-focused summary>"
when_to_use: "<triggers + example phrasings + anti-shortcut suffix>"
argument-hint: "[...]"
model: sonnet
effort: high
allowed-tools: Bash(git *) Read
paths: "**/*.ext"
disable-model-invocation: true
---

## Steps

[The actual workflow. No summary at the top. Jump straight into the first step.]

Optional companion folders. A skill is a folder, not just a single file. When SKILL.md grows large or needs supporting assets, split content out:

<skill-name>/
├── SKILL.md            # required
├── scripts/            # optional — executable code (Python, Bash, etc.)
├── references/         # optional — detailed docs, loaded only when needed
└── assets/             # optional — templates, fonts, icons

Reference these from SKILL.md by path (e.g. See references/api-patterns.md for rate limiting guidance). Do not add a README.md inside the skill folder — all human-facing documentation belongs in SKILL.md or references/. A repo-level README is fine when distributing via GitHub; it just must not live inside the skill directory itself.

Rules for description:

  • One sentence, outcome-focused.
  • Good: "Reviews a PR and reports issues grouped by severity."
  • Bad: "Gets the diff via gh, runs composer lint, writes numbered comments." (too implementation-specific; invites shortcut-following.)
  • Never stuff trigger phrases into description; they belong in when_to_use.

Rules for when_to_use:

  • Start with "Use when the user..." and list concrete triggers.
  • Include the anti-shortcut suffix: Follow all steps in order; do not shortcut based on this description.
  • description and when_to_use are concatenated in the skill listing and share a 1,536-character cap. Keep both tight.
  • Add negative triggers when over-triggering is a real risk: Do NOT use for [adjacent case] (use [other-skill] instead). This is more effective than tightening the positive trigger phrasing alone.

Rules for the body:

  • Do not open with a paragraph summarising what the skill does. Jump directly to Step 1.
  • Steps should be imperative and specific. "Search for X before asking" is better than "You may want to consider searching for X."
  • If parts of the workflow must be followed exactly (no adaptation), mark them explicitly: This step is not optional.
  • For sections that must not be skipped, prefer a dedicated ## Important or ## Critical heading over inline bold. Headers are harder to skim past than emphasis inside a paragraph.

5. Pressure-test before finalising

Run two mental tests.

If an agent read only description + when_to_use, what would it do?

The right answer is "decide whether this skill applies to

阅读完整来源 ↗