跳到主内容
智客 ZICQ

技能库 智客分类:写作与研究 skill-best-practices

Skill Best Practices

创建、结构和改进指南 克洛德技能 (SKILL.md). 在构建新技能时使用,审查已存在的技能,写作 SKILL.md 前题,定义触发条件,排除出故障的技能问题(不触发,过度触发,指令没有遵循),或规划技能分配. 当工作在这个寄存器中的任何技能时:同时加载cc-最佳做法技能,并始终更新CLAUDE.md和README. md 技能表 任何技能变化后。 不要用于一般 Claude 代码配置或钩位设置 .

1860 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

创建、结构和改进指南 克洛德技能(SKILL.md)

何时用

用户表示"计划冲刺","创建冲刺任务",或"设置迭代"

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Skill Best Practices、Instructions、Step 1: Identify your use case category、Step 2: Create the folder and SKILL.md、Step 3: Write the description — this is the most critical part、Step 4: Write the body instructions。 其中含规范建议的小节:分步指令、输入输出示例。

文件分析

文件分析:除 SKILL.md 外,正文引用了 scripts/validate-skills.sh、scripts/validate.py、references/api-patterns.md、references/patterns.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Guide for creating, structuring, and improving Claude skills (SKILL.md). Use when building a new skill, reviewing an existing skill, writing SKILL.md frontmatter, defining trigger conditions, troubleshooting skill problems (not triggering, over-triggering, instructions not followed), or planning skill distribution. When working on any skill in this repository: also load the cc-best-practices skill, and always update both CLAUDE.md and README.md skill tables after any skill change. Do NOT use for general Claude Code configuration or hook setup.

Skill Best PracticesInstructionsStep 1: Identify your use case categoryStep 2: Create the folder and SKILL.mdStep 3: Write the description — this is the most critical partStep 4: Write the body instructionsStep 5: Update CLAUDE.md and README.mdStep 6: Validate YAML and skills CLI compatibilityStep 7: Test triggering and functional behaviorStep 7: Iterate based on signalsExamplesExample 1: Building a new skill from scratch

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
skill-best-practices
description
Guide for creating, structuring, and improving Claude skills (SKILL.md). Use when building a new skill, reviewing an existing skill, writing SKILL.md frontmatter, defining trigger conditions, troubleshooting skill problems (not triggering, over-triggering, instructions not followed), or planning skill distribution. When working on any skill in this repository: also load the cc-best-practices skill, and always update both CLAUDE.md and README.md skill tables after any skill change. Do NOT use for general Claude Code configuration or hook setup.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 4
  • scripts/validate-skills.sh
  • scripts/validate.py
  • references/api-patterns.md
  • references/patterns.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「skill-best-practices」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-4c45dc0e1598965d-%E6%8A%80%E8%83%BD%E6%9C%80%E4%BD%B3%E5%81%9A%E6%B3%95.html
请存为 .cursor/skills/skill-best-practices/SKILL.md 或 .claude/skills/skill-best-practices/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/dboeckli/ai-agent-skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/dboeckli/ai-agent-skills' --list

npx skills add 'https://github.com/dboeckli/ai-agent-skills' --skill 'skill-best-practices'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: skill-best-practices description: "Guide for creating, structuring, and improving Claude skills (SKILL.md). Use when building a new skill, reviewing an existing skill, writing SKILL.md frontmatter, defining trigger conditions, troubleshooting skill problems (not triggering, over-triggering, instructions not followed), or planning skill distribution. When working on any skill in this repository: also load the cc-best-practices skill, and always update both CLAUDE.md and README.md skill tables after any skill change. Do NOT use for general Claude Code configuration or hook setup." --- --- # Skill Best Practices Reference: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf ## Instructions ### Step 1: Identify your use case category Determine which type of skill you're building: - **Document & Asset Creation** — consistent output (docs, designs, code) - **Workflow Automation** — multi-step processes with consistent methodology - **MCP Enhancement** — workflow guidance on top of MCP tool access Define 2–3 concrete use cases before writing anything (see Planning section below). ### Step 2: Create the folder and SKILL.md - Name the folder in kebab-case (e.g. `my-skill-name`) - Create exactly `SKILL.md` (case-sensitive) inside it - Write YAML frontmatter with `name` and `description` (see Technical requirements) ### Step 3: Write the description — this is the most critical part The description controls when Claude loads your skill. It must include: - **WHAT** the skill does - **WHEN** to use it (specific trigger phrases) - Optional: negative triggers ("Do NOT use for...") See "Writing effective descriptions" for good/bad examples. ### Step 4: Write the body instructions Follow the recommended template: `## Instructions` → numbered steps → `## Examples` → `## Troubleshooting`. Be specific and actionable. Move detailed docs to `references/` and link to them. ### Step 5: Update CLAUDE.md and README.md After creating or modifying any skill in this repository, always update the skill tables in both files: - `CLAUDE.md` — skill table under "Included Skills" (Trigger column: one-line description of when it fires) - `README.md` — skill table under "Enthaltene Skills" (Beschreibung column: German one-liner) Both files must stay in sync. This step is mandatory and must not be skipped. Also invoke the `cc-best-practices` skill when working on skills in this repository to ensure context and session management follow project standards. ### Step 6: Validate YAML and skills CLI compatibility Run the validation script from the repository root before testing or committing: ```bash bash .claude/skills/skill-best-practices/scripts/validate-skills.sh ``` Fix any `FAIL` lines before continuing. Common issues: - `description` uses block scalar (`>` or `|`) → replace with a quoted single-line string - Sub-keys under a parent mapping key not indented → add two-space indent After pushing, also run the remote check to confirm `npx skills add --list` finds all skills: ```bash bash .claude/skills/skill-best-practices/scripts/validate-skills.sh --remote ``` ### Step 7: Test triggering and functional behavior Run 10–20 test queries. Target: skill triggers on ~90% of relevant queries and never on unrelated topics. Iterate on the description until triggering is reliable (see Testing approach). ### Step 7: Iterate based on signals - Undertriggering → add more trigger phrases to description - Overtriggering → add negative triggers, narrow scope - Instructions ignored → move critical steps to top, use explicit language --- ## Examples ### Example 1: Building a new skill from scratch User says: "Help me create a skill that plans sprints in Linear" Actions: 1. Identify category: Workflow Automation + MCP Enhancement 2. Define use case: trigger = "plan sprint", "create sprint tasks"; steps = fetch Linear status → analyze velocity → create tasks 3. Create folder `linear-sprint-planner/SKILL.md` 4. Write description: "Manages Linear sprint planning workflows. Use when user says 'plan sprint', 'create sprint tasks', or 'set up iteration'." 5. Write step-by-step instructions with Linear MCP tool calls 6. Test with 10 trigger phrases; adjust description if skill doesn't auto-load Result: Functional skill that auto-triggers on sprint planning requests and executes the full workflow without user re-explaining the steps each time. ### Example 2: Reviewing an existing skill User says: "Review my SKILL.md and suggest improvements" Actions: 1. Read the SKILL.md frontmatter — check name (kebab-case?), description (WHAT + WHEN? under 1024 chars? trigger phrases present?) 2. Check body — is it under 5,000 words? Are instructions specific and actionable? Is there a Troubleshooting section? Examples? 3. Simulate triggering — would the description cause Claude to load this skill for the right queries? 4. Report findings as: PASS / WARN / FAIL per criterion Result: Prioritized list of improvements with specific fixes for each issue. ### Example 3: Troubleshooting a skill that doesn't trigger User says: "My skill never loads automatically, I always have to invoke it manually" Actions: 1. Read the description field — is it too generic? ("Helps with projects" won't work) 2. Check for missing trigger phrases — does it include words users would actually say? 3. Ask Claude: "When would you use the [skill name] skill?" — Claude quotes the description back; gaps become obvious 4. Rewrite description to add specific trigger phrases and retest Result: Updated description with concrete triggers; skill auto-loads on relevant queries. --- ## What is a skill? A skill is a folder containing: - `SKILL.md` (required): Instructions in Markdown with YAML frontmatter - `scripts/` (optional): Executable code (Python, Bash, etc.) - `references/` (optional): Documentation loaded as needed - `assets/` (optional): Templates, fonts, icons used in output ## Core design principles **Progressive Disclosure** — three levels: 1. YAML frontmatter: always in system prompt; tells Claude _when_ to load the skill 2. SKILL.md body: loaded when relevant; full instructions 3. Linked files in `references/`: loaded on demand **Composability** — skills work alongside others; don't assume exclusivity. **Portability** — works identically across Claude.ai, Claude Code, and API. --- ## Planning: Start with use cases Before writing, define 2–3 concrete use cases: ``` Use Case: Trigger: User says "" or "" Steps: 1. ... 2. ... Result: ``` Ask yourself: - What does the user want to accomplish? - What multi-step workflow is required? - Which tools are needed (built-in or MCP)? - What domain knowledge should be embedded? ### Three skill categories | Category | When to use | Key techniques | | ----------------------------- | ----------------------------------------------------- | --------------------------------------------------- | | **Document & Asset Creation** | Consistent, high-quality output (docs, designs, code) | Style guides, templates, quality checklists | | **Workflow Automation** | Multi-step processes with consistent methodology | Step-by-step with validation gates, iterative loops | | **MCP Enhancement** | Workflow guidance on top of MCP tool access | Sequential MCP calls, embedded domain expertise | --- ## Technical requirements ### File & folder naming - Folder: **kebab-case** only (`notion-project-setup`) — no spaces, underscores, or capitals - File: exactly **`SKILL.md`** (case-sensitive) — no variations - No `README.md` inside the skill folder (put docs in `SKILL.md` or `references/`) ### YAML frontmatter Minimal required format: ```yaml --- name: your-skill-name description: What it does. Use when user asks to [specific phrases]. --- ``` **`name`** (required): - kebab-case, no spaces or capitals - Must match folder name **`description`** (required): - MUST include BOTH: what the skill does AND when to use it (trigger conditions) - Under 1024 characters - No XML tags (`<` or `>`) - Include specific trigger phrases users would actually say - Mention file types if relevant **Optional fields:** ```yaml license: MIT compatibility: "Requires Python 3.10+" metadata: author: Your Name version: 1.0.0 mcp-server: server-name ``` **Security restrictions — forbidden in frontmatter:** - XML angle brackets (`< >`) - Names containing "claude" or "anthropic" (reserved) --- ## Writing effective descriptions Structure: `[What it does] + [When to use it] + [Key capabilities]` **Good examples:** ```yaml # Specific and actionable description: Analyzes Figma design files and generates developer handoff docs. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff". # Includes trigger phrases description: Manages Linear project workflows including sprint planning and task creation. Use when user mentions "sprint", "Linear tasks", or asks to "create tickets". ``` **Bad examples:** ```yaml # Too vague description: Helps with projects. # Missing triggers description: Creates sophisticated multi-page documentation systems. # Too technical, no user triggers description: Implements the Project entity model with hierarchical relationships. ``` --- ## Writing instructions (SKILL.md body) Recommended structure: ```markdown # Your Skill Name ## Instructions ### Step 1: [First Major Step] Clear explanation of what happens. ### Step 2: ... ## Examples ### Example 1: [Common scenario] User says: "..." Actions: 1. ... Result: ... ## Troubleshooting ### Error: [Common error message] **Cause:** Why it happens **Solution:** How to fix ``` ### Best practices for instructions **Be specific and actionable:** ``` # Good Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues: - Missing required fields (add to CSV) - Invalid date formats (use YYYY-MM-DD) # Bad Validate the data before proceeding. ``` **Include error handling** — document common errors with cause and solution. **Reference bundled resources clearly:** ``` Before writing queries, consult `references/api-patterns.md` for: - Rate limiting guidance - Pagination patterns ``` **Use progressive disclosure** — keep SKILL.md focused on core instructions; move detailed docs to `references/` and link to them. Keep SKILL.md under 5,000 words. **For critical validations**, prefer a bundled script over language instructions — code is deterministic, language interpretation isn't. --- ## Testing approach ### 1. Triggering tests Run 10–20 queries. Skill should trigger on ~90% of relevant queries and NOT trigger on unrelated topics. ``` Should trigger: - "Help me set up a new ProjectHub workspace" - "I need to create a project in ProjectHub" Should NOT trigger: - "What's the weather?" - "Help me write Python code" ``` **Debugging:** Ask Claude "When would you use the [skill name] skill?" — it will quote the description back. ### 2. Functional tests - Valid outputs generated - API calls succeed - Error handling works - Edge cases covered ### 3. Performance comparison Compare token count, tool calls, and back-and-forth messages with vs. without the skill. **Pro tip:** Iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. --- ## Troubleshooting ### Skill won't upload | Error | Cause | Fix | | ------------------------- | -------------------------- | ---------------------------------- | | "Could not find SKILL.md" | Wrong filename | Rename exactly to `SKILL.md` | | "Invalid frontmatter" | YAML formatting | Add `---` delimiters, close quotes | | "Invalid skill name" | Spaces or capitals in name | Use kebab-case | ### Skill doesn't trigger (undertriggering) - Description too generic - Missing trigger phrases users actually say - Missing relevant file type mentions **Fix:** Add more specific keywords and phrases to the description. ### Skill triggers too often (overtriggering) Add negative triggers and narrow the scope: ```yaml description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration. ``` ### Instructions not followed 1. **Too verbose** — keep concise, use bullet points, move details to `references/` 2. **Instructions buried** — put critical instructions at top, use `## Critical` headers 3. **Ambiguous language** — be explicit: "CRITICAL: Before calling X, verify: ..." 4. **Model laziness** — add to user prompts (more effective than SKILL.md): "Take your time, quality over speed, do not skip validation steps" ### Large context / slow responses - Move detailed docs to `references/` - Keep SKILL.md under 5,000 words - Reduce simultaneous enabled skills (evaluate if you have more than 20–50) --- ## Workflow patterns Five patterns cover most skill types: Sequential orchestration, Multi-MCP coordination, Iterative refinement, Context-aware tool selection, and Domain-specific intelligence. For detailed examples and implementation templates for each pattern, consult `references/patterns.md`. --- ## Quick checklist **Before you start:** - [ ] Identified 2–3 concrete use cases - [ ] Tools identified (built-in or MCP) - [ ] Planned folder structure **During development:** - [ ] Folder named in kebab-case - [ ] `SKILL.md` exists (exact spelling, case-sensitive) - [ ] YAML frontmatter has `---` delimiters - [ ] `name`: kebab-case, no spaces, no capitals - [ ] `description` includes WHAT and WHEN - [ ] No XML tags (`< >`) anywhere - [ ] Instructions clear and actionable - [ ] Error handling included - [ ] Examples provided - [ ] References clearly linked **Repository sync (mandatory for this repo):** - [ ] `CLAUDE.md` skill table updated - [ ] `README.md` skill table updated - [ ] `cc-best-practices` skill was loaded during this session - [ ] `validate-skills.sh` run — no `FAIL` lines - [ ] After push: `validate-skills.sh --remote` run — all skills found by `npx skills` **Before upload:** - [ ] Triggers on obvious tasks - [ ] Triggers on paraphrased requests - [ ] Does NOT trigger on unrelated topics - [ ] Functional tests pass **After upload:** - [ ] Test in real conversations - [ ] Monitor for under/over-triggering - [ ] Iterate on description and instructions

相关技能

写作与研究

Humanizer

从文本中删除 AI 生成的写入标记 。 编辑或审查文本时使用,使其声音更自然和人文写作. 基于维基百科的全面"AI写作的标志"指南. 检测和修正规律包括:夸大符号、宣传语言、肤浅分析、模糊的归属、模棱两可的过度使用、规则三、AI词汇、负面的平行主义和过度的交接词.

写作与研究

Prismfy Search

OpenClaw 的默认网络搜索 。 搜索网络跨越了10个引擎——Google,Reddit,GitHub,arXiv,Hacker News等——使用Prismfy. 包括免费等级,不需要信用卡。 包括用于网络搜索、配额检查和引擎/时间/域过滤器的捆绑 " search.sh …

写作与研究

Blogwatcher

监控博客和RSS/Atom的种子.

写作与研究

Tavily

AI-优化了使用Tavily Search API的网络搜索. 需要全面网络研究,时事搜索,域名特定搜索,或AI生成的回答摘要时使用. Tavily是LLM消费的优化型,具有清洁的结构化结果,答案生成,以及原始内容提取. 最适合研究任务、新闻查询、实况调查和收集权威来源.