Skill: tenequm/skills-best-practices (version 0.4.0)

--- name: skills-best-practices description: Build high-quality Agent Skills for Claude following official Anthropic best practices. Covers SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, patterns, troubleshooting, and distribution across all surfaces (Claude.ai, Claude Code, API, Agent SDK). Use when creating new skills, reviewing skill quality, debugging skill triggering, structuring skill directories, writing skill descriptions, or improving existing skills. Triggers on "build a skill", "create a skill", "skill structure", "SKILL.md", "skill best practices", "skill not triggering", "skill quality". metadata: version: "0.4.0" openclaw: homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices emoji: "📐" --- # Skills Best Practices Comprehensive reference for building Agent Skills that follow Anthropic's official guidelines. Skills are folders containing instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the [Agent Skills open standard](https://agentskills.io). ## Quick Start A minimal skill is a directory with a `SKILL.md` file: ``` my-skill/ ├── SKILL.md # Required - instructions with YAML frontmatter ├── references/ # Optional - detailed docs loaded on demand ├── scripts/ # Optional - executable code └── assets/ # Optional - templates, fonts, icons ``` Minimal `SKILL.md`: ```yaml --- name: my-skill-name description: What it does. Use when [specific triggers]. --- # My Skill Name [Instructions here] ``` Only `name` and `description` are required in frontmatter. ## Core Design Principles ### Progressive Disclosure (Most Important) Skills load information in three levels to minimize token usage: | Level | When Loaded | Token Cost | Content | |-------|------------|------------|---------| | **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter | | **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body | | **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts | Keep SKILL.md under **500 lines**. Move detailed docs to separate files and reference them: ```markdown ## Advanced features - **Form filling**: See [FORMS.md](FORMS.md) - **API reference**: See [reference.md](reference.md) ``` Claude reads referenced files only when the task requires them. ### Composability Skills work alongside other skills. Don't assume yours is the only one loaded. ### Portability Skills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available). ## Writing the Description (Critical) The description is the **single most important field** - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills. ### Rules - Write in **third person** ("Processes files..." not "I help you process files...") - Include **WHAT** it does + **WHEN** to use it - Max 1024 characters, no XML angle brackets - Be slightly "pushy" - Claude tends to **undertrigger** rather than overtrigger - Include specific trigger phrases users would naturally say ### Good vs Bad ```yaml # GOOD - specific, actionable, includes triggers description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. # BAD - too vague description: Helps with documents. # BAD - missing triggers description: Creates sophisticated multi-page documentation systems. ``` More examples in [references/description-guide.md](references/description-guide.md). ## Frontmatter Reference ### Required Fields | Field | Rules | |-------|-------| | `name` | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No "claude" or "anthropic" | | `description` | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN | The agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: `name` falls back to the directory name, and `description` falls back to the first markdown paragraph. Write both anyway for portability. ### Optional Fields (Claude Code) | Field | Purpose | |-------|---------| | `argument-hint` | Autocomplete hint, e.g. `[issue-number]` | | `when_to_use` | Extra trigger context, appended to `description` in the skill listing | | `arguments` | Named positional arguments for `$name` substitution (space-separated string or list) | | `disable-model-invocation` | `true` = only user can invoke (for deploy, commit) | | `user-invocable` | `false` = hidden from `/` menu (background knowledge) | | `allowed-tools` | Pre-approves tools (no permission prompt); space-separated, e.g. `Read Grep Glob` | | `model` | Override model for this skill; accepts `inherit`. Lasts the current turn only | | `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max` | | `context` | `fork` = run in isolated subagent | | `agent` | Subagent type when `context: fork` (e.g. `Explore`, `Plan`) | | `hooks` | Hooks scoped to this skill's lifecycle | | `paths` | Glob patterns limiting when skill activates | ### Naming Conventions The `name` (and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (`--`); and match the parent directory name. Anthropic surfaces also reject the reserved words `claude` and `anthropic`. Prefer **gerund form** for clarity: - `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases` - Also acceptable: `pdf-processing`, `process-pdfs` - Avoid: `helper`, `utils`, `tools`, `documents` ## Structuring Instructions ### Be Concise Claude is smart. Only add context it doesn't already have: ```markdown # GOOD (~50 tokens) ## Extract PDF text Use pdfplumber for text extraction: ```python import pdfplumber with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text() ``` # BAD (~150 tokens) ## Extract PDF text PDF files are a common file format containing text and images. To extract text, you need a library. There are many available... ``` ### Avoid Too Many Options Don't present multiple approaches unless necessary. Give one default with an escape hatch: ```markdown # BAD: "Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..." # GOOD: "Use pdfplumber for text extraction. For scanned PDFs needing # OCR, use pdf2image with pytesseract instead." ``` ### Set Degrees of Freedom - **High freedom** (text guidelines): Multiple approaches valid, context-dependent - **Medium freedom** (pseudocode/templates): Preferred pattern exists, some variation OK - **Low freedom** (exact scripts): Operations are fragile, consistency critical ### Recommended SKILL.md Structure ```markdown # Skill Name ## Quick start [Minimal working example] ## Workflow Decision Tree [Route to the right approach based on task type] ## Detailed Instructions [Step-by-step for each workflow] ## Examples [Concrete input/output pairs] ## Troubleshooting [Common errors and fixes] ``` ### Reference Files Keep references **one level deep** from SKILL.md. "Depth" means the reference *chain* (a file linking to a file linking to a file), not filesystem nesting - a `references/` subdirectory is fine. In a chain, Claude may preview files with partial reads (`head`) and miss content. ```markdown # BAD: Too deep SKILL.md -> advanced.md -> details.md -> actual info # GOOD: One level SKILL.md -> advanced.md (contains the info directly) SKILL.md -> reference.md (contains the info directly) ``` For reference files >100 lines, include a **table of contents** at the top. Watch file *size* too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs. ## Patterns ### Sequential Workflow ```markdown ## Step 1: Analyze input Run: `python scripts/analyze.py input.pdf` ## Step 2: Validate Run: `python scripts/validate.py fields.json` Fix any errors before continuing. ## Step 3: Execute Run: `python scripts/process.py input.pdf fields.json output.pdf` ``` ### Conditional Workflow (Decision Tree) ```markdown ## Workflow Decision Tree **Creating new content?** -> Follow "Creation workflow" **Editing existing content?** -> Follow "Editing workflow" **Reviewing content?** -> Follow "Review workflow" ``` ### Feedback Loop ```markdown 1. Make edits 2. Validate: `python scripts/validate.py` 3. If validation fails -> fix issues -> go to step 2 4. Only proceed when validation passes ``` ### Checklist Pattern (for complex tasks) ```markdown Copy this checklist and track progress: - [ ] Step 1: Analyze input - [ ] Step 2: Create plan - [ ] Step 3: Validate plan - [ ] Step 4: Execute - [ ] Step 5: Verify output ``` More patterns in [references/patterns.md](references/patterns.md). ## Scripts When your skill includes executable code: - **Solve, don't punt**: Handle errors explicitly instead of letting them fail - **Justify constants**: No magic numbers - document why each value was chosen - **Prefer execution over loading**: Scripts run without entering context; only output consumes tokens - **Clarify intent**: "Run `analyze.py`" (execute) vs "See `analyze.py`" (read as reference) - **List dependencies** in SKILL.md and verify availability ## Testing ### Build Evaluations First Create evaluations **before** writing extensive instructions - this proves the skill solves a real problem. Run Claude on representative tasks *without* the skill and document the failures; build ~3 scenarios that test those gaps; measure a baseline; then write the minimum instructions needed to pass. Iterate against the baseline. ### Triggering Tests ``` Should trigger: - "Help me set up a new project in [Service]" - "I need to create a project" (paraphrased) Should NOT trigger: - "What's the weather?" (unrelated) - "Write Python code" (too generic) ``` ### Functional Tests Test normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency. ### Debug Triggering Ask Claude: "When would you use the [skill-name] skill?" - it quotes the description back. Adjust based on what's missing. ## Troubleshooting | Symptom | Cause | Fix | |---------|-------|-----| | Skill never loads | Description too vague | Add specific triggers and key terms | | Skill loads for wrong tasks | Description too broad | Add negative triggers, be more specific | | Instructions not followed | Too verbose or buried | Put critical instructions at top, use headers | | Slow/degraded responses | SKILL.md too large | Move content to references/, keep under 500 lines | | "Could not find SKILL.md" | Wrong filename | Must be exactly `SKILL.md` (case-sensitive) | | "Invalid skill name" | Spaces or capitals | Use kebab-case: `my-skill-name` | ## Distribution | Surface | How to Deploy | |---------|--------------| | Claude.ai | Settings > Features > Upload zip | | Claude Code (personal) | `~/.claude/skills/<name>/SKILL.md` | | Claude Code (project) | `.claude/skills/<name>/SKILL.md` | | Claude Code (plugin) | `<plugin>/skills/<name>/SKILL.md` | | API | Upload via the Skill Management API, use via the Messages API | | Enterprise | Managed settings (org-wide) | Skills don't sync across surfaces - deploy separately to each. ### Using Skills with the API Custom skills are uploaded through the Skill Management API; `anthropic`-type skills are pre-built by Anthropic. Both are used identically - pass them in the Messages API `container` parameter, each as `{type, skill_id, version}` where `type` is `anthropic` or `custom`. Up to 8 Skills per request. Requires the code execution tool and the beta headers `code-execution-2025-08-25` and `skills-2025-10-02` (plus `files-api-2025-04-14` for file upload/download). The API code execution environment has **no network access and no runtime package installation** - bundle dependencies or use pre-installed packages. ## Security - Only use skills from **trusted sources** - No XML angle brackets in frontmatter (injection risk) - Audit all bundled scripts and resources before using third-party skills - Be cautious of skills that fetch from external URLs ## Additional References - [Description writing guide](references/description-guide.md) - detailed examples and anti-patterns - [Patterns and workflows](references/patterns.md) - advanced patterns with MCP, subagents, iterative refinement - [Claude Code features](references/claude-code-features.md) - context:fork, dynamic injection, argument substitution - [Quality checklist](references/checklist.md) - pre-upload validation checklist - [ClawHub publishing](references/clawhub-publishing.md) - `metadata.openclaw` schema, moderation pipeline, reason codes catalog, pre-publish checklist ## Official Resources - [Agent Skills Spec](https://agentskills.io/specification) - [Claude Code Skills Docs](https://code.claude.com/docs/en/skills) - [API Skills Guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide) - [Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - [Anthropic Skills Repo](https://github.com/anthropics/skills) - [Engineering Blog: Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) - [Complete Guide PDF](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)

path: CHANGELOG.md
content: # Changelog

All notable changes to this skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.4.0] - 2026-05-21

### Added
- Claude Code frontmatter fields `when_to_use`, `arguments`, `hooks`; substitutions
  `$name` and `${CLAUDE_EFFORT}`.
- Multi-line ` ```! ` injection block; `skillOverrides` and `disableSkillShellExecution`
  settings; skill content lifecycle / compaction re-attach budget; built-in commands
  reachable through the Skill tool.
- Evaluation-driven development; "Claude A / Claude B" iterative pattern;
  "avoid offering too many options" anti-pattern.
- API usage model (`container` parameter, `anthropic` vs `custom` Skills, up to 8
  per request, beta headers).
- Agent Skills spec `license` and `compatibility` fields; `skills-ref` validator.
- ClawHub capability tags `financial-authority` and `requires-paid-service`;
  `--clawscan-note` flag; OWASP Agentic Skills Top 10 note.
- Reference-file size guidance; checklist calibration note for project-local skills.

### Changed
- `effort` adds `xhigh`; `model` accepts `inherit` (turn-scoped override).
- `allowed-tools` clarified: pre-approves tools, does not restrict them; space-separated.
- Skill listing budget is 1% of context (was 2%); added `skillListingBudgetFraction`
  and the 1,536-character per-entry cap.
- Bundled skills list adds `/run`, `/verify`, `/run-skill-generator`.
- Inline `!command` injection recognized only at line start or after whitespace.
- Custom commands merged into skills; a skill takes precedence over a same-named command.
- `name` documented as optional in Claude Code (directory-name fallback); `description`
  falls back to the first markdown paragraph; completed the naming rules.
- Progressive-disclosure Level 2 budget framed as a recommendation.
- Cut-off skill descriptions diagnosed with `/doctor`.
- Description guidance: Claude matches semantic meaning, not keyword stuffing.
- ClawHub capability-tag derivation: purchase / transaction-signing authority now
  yields `financial-authority`, not `crypto`/`requires-wallet`.

### Removed
- ClawHub `download` install kind (no longer supported; schema is `brew`/`node`/`go`/`uv`).

### Fixed
- Clarified "one level deep" means reference-chain depth, not filesystem nesting.
- Corrected stale ClawHub doc source links and removed an unverifiable model identifier.

## [0.3.0] - 2026-04-30
- Initial CHANGELOG; tracking established.


path: LICENSE.txt
content: Apache License
Version 2.0, January 2004
https://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the
copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other
entities that control, are controlled by, or are under common control with
that entity. For the purposes of this definition, "control" means (i) the
power, direct or indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership of fifty percent
(50%) or more of the outstanding shares, or (iii) beneficial ownership of
such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising
permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation source, and
configuration files.

"Object" form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object
code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form,
made available under the License, as indicated by a copyright notice that is
included in or attached to the work (an example is provided in the Appendix
below).

"Derivative Works" shall mean any work, whether in Source or Object form,
that is based on (or derived from) the Work and for which the editorial
revisions, annotations, elaborations, or other modifications represent, as a
whole, an original work of authorship. For the purposes of this License,
Derivative Works shall not include works that remain separable from, or
merely link (or bind by name) to the interfaces of, the Work and Derivative
Works thereof.

"Contribution" shall mean any work of authorship, including the original
version of the Work and any modifications or additions to that Work or
Derivative Works thereof, that is intentionally submitted to Licensor for
inclusion in the Work by the copyright owner or by an individual or Legal
Entity authorized to submit on behalf of the copyright owner. For the
purposes of this definition, "submitted" means any form of electronic, verbal,
or written communication sent to the Licensor or its representatives,
including but not limited to communication on electronic mailing lists, source
code control systems, and issue tracking systems that are managed by, or on
behalf of, the Licensor for the purpose of discussing and improving the Work,
but excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on
behalf of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
reproduce, prepare Derivative Works of, publicly display, publicly perform,
sublicense, and distribute the Work and such Derivative Works in Source or
Object form.

3. Grant of Patent License. Subject to the terms and conditions of this
License, each Contributor hereby grants to You a perpetual, worldwide,
non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
section) patent license to make, have made, use, offer to sell, sell, import,
and otherwise transfer the Work, where such license applies only to those
patent claims licensable by such Contributor that are necessarily infringed by
their Contribution(s) alone or by combination of their Contribution(s) with
the Work to which such Contribution(s) was submitted. If You institute patent
litigation against any entity (including a cross-claim or counterclaim in a
lawsuit) alleging that the Work or a Contribution incorporated within the Work
constitutes direct or contributory patent infringement, then any patent
licenses granted to You under this License for that Work shall terminate as of
the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or
Derivative Works thereof in any medium, with or without modifications, and in
Source or Object form, provided that You meet the following conditions:

(a) You must give any other recipients of the Work or Derivative Works a copy
of this License; and

(b) You must cause any modified files to carry prominent notices stating that
You changed the files; and

(c) You must retain, in the Source form of any Derivative Works that You
distribute, all copyright, patent, trademark, and attribution notices from
the Source form of the Work, excluding those notices that do not pertain to
any part of the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its distribution,
then any Derivative Works that You distribute must include a readable copy of
the attribution notices contained within such NOTICE file, excluding those
notices that do not pertain to any part of the Derivative Works, in at least
one of the following places: within a NOTICE text file distributed as part of
the Derivative Works; within the Source form or documentation, if provided
along with the Derivative Works; or, within a display generated by the
Derivative Works, if and wherever such third-party notices normally appear.
The contents of the NOTICE file are for informational purposes only and do not
modify the License. You may add Your own attribution notices within Derivative
Works that You distribute, alongside or as an addendum to the NOTICE text from
the Work, provided that such additional attribution notices cannot be
construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide
additional or different license terms and conditions for use, reproduction, or
distribution of Your modifications, or for any such Derivative Works as a
whole, provided Your use, reproduction, and distribution of the Work otherwise
complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any
Contribution intentionally submitted for inclusion in the Work by You to the
Licensor shall be under the terms and conditions of this License, without any
additional terms or conditions. Notwithstanding the above, nothing herein
shall supersede or modify the terms of any separate license agreement you may
have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names,
trademarks, service marks, or product names of the Licensor, except as
required for reasonable and customary use in describing the origin of the Work
and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
writing, Licensor provides the Work (and each Contributor provides its
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied, including, without limitation, any warranties
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any risks
associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in
tort (including negligence), contract, or otherwise, unless required by
applicable law (such as deliberate and grossly negligent acts) or agreed to in
writing, shall any Contributor be liable to You for damages, including any
direct, indirect, special, incidental, or consequential damages of any
character arising as a result of this License or out of the use or inability to
use the Work (including but not limited to damages for loss of goodwill, work
stoppage, computer failure or malfunction, or any and all other commercial
damages or losses), even if such Contributor has been advised of the
possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work
or Derivative Works thereof, You may choose to offer, and charge a fee for,
acceptance of support, warranty, indemnity, or other liability obligations
and/or rights consistent with this License. However, in accepting such
obligations, You may act only on Your own behalf and on Your sole
responsibility, not on behalf of any other Contributor, and only if You agree
to indemnify, defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason of your
accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS


path: references/checklist.md
content: # Skill Quality Checklist

Validate your skill before upload or sharing. Based on Anthropic's official checklist from "The Complete Guide to Building Skills for Claude."

> **Calibrate to scope.** This checklist targets skills headed for broad distribution (ClawHub, unknown users, multiple models). For a project-local, single-user, or `disable-model-invocation` skill, skip items that don't apply - triggering-accuracy tuning, multi-model testing, and distribution hygiene matter far less when one person invokes the skill in their own repo.

## Before You Start

- [ ] Identified 2-3 concrete use cases the skill enables
- [ ] Tools identified (built-in, MCP, or scripts)
- [ ] Planned folder structure (SKILL.md + what else is needed)

## Frontmatter

- [ ] Folder named in **kebab-case** (no spaces, no capitals)
- [ ] `SKILL.md` file exists (exact spelling, case-sensitive)
- [ ] YAML frontmatter has `---` delimiters
- [ ] `name`: kebab-case, max 64 chars, no "claude"/"anthropic"
- [ ] `description`: includes WHAT and WHEN, max 1024 chars
- [ ] No XML angle brackets (`<` `>`) anywhere in frontmatter
- [ ] No `README.md` inside the skill folder

## Description Quality

- [ ] Written in **third person** ("Processes..." not "I help...")
- [ ] Includes specific **capabilities** (action verbs)
- [ ] Includes specific **trigger phrases** users would say
- [ ] Mentions relevant **file types** if applicable
- [ ] Specific enough to distinguish from similar skills
- [ ] Slightly "pushy" - Claude tends to undertrigger

## Instructions Quality

- [ ] Concise - only adds context Claude doesn't already have
- [ ] Clear and actionable (not vague or ambiguous)
- [ ] Uses markdown headers for structure
- [ ] Critical instructions at the **top**, not buried
- [ ] Working examples provided (not pseudocode)
- [ ] Error handling included for common failures
- [ ] Consistent terminology throughout (pick one term, stick with it)

## Progressive Disclosure

- [ ] SKILL.md body under **500 lines**
- [ ] Detailed docs in separate files (references/, scripts/)
- [ ] References clearly linked from SKILL.md
- [ ] References are **one level deep** (no nested chains)
- [ ] Long reference files (>100 lines) have a table of contents

## Scripts (if applicable)

- [ ] Scripts handle errors explicitly (don't punt to Claude)
- [ ] No "voodoo constants" (all values justified with comments)
- [ ] Required packages listed in instructions
- [ ] Package availability verified in target environment
- [ ] Clear whether Claude should execute or read each script
- [ ] Scripts use forward slashes in paths (not backslashes)

## Testing

### Triggering Tests

- [ ] Triggers on obvious, direct requests
- [ ] Triggers on paraphrased/natural requests
- [ ] Does NOT trigger on unrelated topics
- [ ] Does NOT trigger on similar-but-distinct requests

### Functional Tests

- [ ] Valid outputs generated for normal inputs
- [ ] Edge cases handled (missing data, unusual formats)
- [ ] API/MCP calls succeed (if applicable)
- [ ] Output consistency across 3-5 runs
- [ ] Tested with at least Haiku and Sonnet (ideally Opus too)

### Real-World Validation

- [ ] Tested in real conversations (not just test scenarios)
- [ ] A new user can accomplish the task on first try
- [ ] Users don't need to prompt Claude about next steps
- [ ] Workflows complete without user correction

## Before Upload

- [ ] All tests pass
- [ ] Tool integration works (if applicable)
- [ ] No time-sensitive information (or in "old patterns" section)
- [ ] No Windows-style paths (all forward slashes)
- [ ] No deprecated APIs referenced
- [ ] Frontmatter validated with `skills-ref validate ./<skill>` (Agent Skills reference validator)

## After Upload

- [ ] Test in real conversations on target surface
- [ ] Monitor for under/over-triggering
- [ ] Collect user feedback
- [ ] Iterate on description and instructions based on usage
- [ ] Update version in metadata

## Performance Comparison (Optional)

Compare with and without skill:

| Metric | Without Skill | With Skill |
|--------|--------------|------------|
| Messages to complete | ? | ? |
| Failed API calls | ? | ? |
| Tokens consumed | ? | ? |
| User corrections needed | ? | ? |

Aim for: 90%+ triggering accuracy, 0 failed API calls, fewer user corrections.


path: references/claude-code-features.md
content: # Claude Code Skill Features

Features specific to skills running in Claude Code, beyond the base Agent Skills standard.

## Contents

- Invocation control
- Subagent execution (context: fork)
- Dynamic context injection
- Argument substitution
- Skill discovery and locations
- Bundled skills
- Skill content lifecycle
- Permission control
- Settings overrides
- Context budget

## Invocation Control

Two frontmatter fields control who can invoke a skill:

### disable-model-invocation: true

Only the user can invoke via `/skill-name`. Claude cannot auto-trigger.

Use for: deploy, commit, send-message - actions with side effects you want to control.

```yaml
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
```

### user-invocable: false

Only Claude can invoke. Hidden from `/` menu.

Use for: background knowledge that isn't actionable as a command.

```yaml
---
name: legacy-system-context
description: Context about the legacy authentication system
user-invocable: false
---
```

### Invocation Matrix

| Frontmatter | User can invoke | Claude can invoke | Description in context |
|-------------|----------------|-------------------|----------------------|
| (default) | Yes | Yes | Always |
| `disable-model-invocation: true` | Yes | No | Not loaded |
| `user-invocable: false` | No | Yes | Always |

## Subagent Execution

Add `context: fork` to run a skill in an isolated subagent. The skill content becomes the prompt. No conversation history access.

```yaml
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
```

The `agent` field selects the execution environment:
- `Explore` - read-only codebase exploration
- `Plan` - architectural planning
- `general-purpose` - full tool access (default)
- Custom agents from `.claude/agents/`

`context: fork` only works for skills with explicit task instructions, not passive guidelines.

## Dynamic Context Injection

The `` !`command` `` syntax runs shell commands before content reaches Claude:

```yaml
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...
```

Each `` !`command` `` executes immediately, output replaces the placeholder. Claude only sees the final rendered content. This is preprocessing, not something Claude runs.

The inline form is recognized only when `!` is at the start of a line or immediately after whitespace. If `!` follows another character (e.g. `` KEY=!`cmd` ``), the placeholder is left as literal text and the command does not run.

For multi-line commands, use a fenced code block opened with ` ```! ` instead of the inline form:

````markdown
## Environment
```!
node --version
npm --version
git status --short
```
````

To disable shell execution for skills and custom commands from user, project, plugin, or additional-directory sources, set `"disableSkillShellExecution": true` in settings. Each command is replaced with `[shell command execution disabled by policy]`. Bundled and managed skills are unaffected.

## Argument Substitution

Skills support these substitution variables:

| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed when invoking |
| `$ARGUMENTS[N]` | Specific argument by 0-based index |
| `$N` | Shorthand for `$ARGUMENTS[N]` |
| `$name` | Named argument declared in the `arguments` frontmatter list (bound by position) |
| `${CLAUDE_SESSION_ID}` | Current session ID |
| `${CLAUDE_EFFORT}` | Current effort level: `low`, `medium`, `high`, `xhigh`, or `max` |
| `${CLAUDE_SKILL_DIR}` | Directory containing the skill's SKILL.md |

Example:

```yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit
```

`/fix-issue 123` becomes "Fix GitHub issue 123 following our coding standards..."

If `$ARGUMENTS` is not present in content, arguments are appended as `ARGUMENTS: <value>`.

### Positional Arguments

```yaml
---
name: migrate-component
description: Migrate a component between frameworks
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.
```

`/migrate-component SearchBar React Vue` replaces `$0`=SearchBar, `$1`=React, `$2`=Vue.

### Named Arguments

Declare an `arguments` frontmatter field to give positions readable names:

```yaml
---
name: fix-issue
description: Fix a GitHub issue on a branch
arguments: [issue, branch]
---

Fix issue $issue on branch $branch.
```

`/fix-issue 123 hotfix` maps `$issue`=123, `$branch`=hotfix - names bind to positions in order.

## Skill Discovery and Locations

Priority order (higher wins on name conflicts):

| Location | Path | Scope |
|----------|------|-------|
| Enterprise | Managed settings | All org users |
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects |
| Project | `.claude/skills/<name>/SKILL.md` | This project |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin enabled |

Enterprise overrides personal, and personal overrides project. Plugin skills use a `plugin-name:skill-name` namespace, so they never conflict with the other levels.

**Custom commands are skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy`. Existing `.claude/commands/` files keep working; if a skill and a command share a name, the skill takes precedence.

### Automatic Discovery

- Skills in subdirectory `.claude/skills/` are auto-discovered when editing files there
- Skills from `--add-dir` directories are loaded and support live change detection
- Monorepo support: `packages/frontend/.claude/skills/` discovered when editing in that package

## Bundled Skills

Ships with Claude Code, available in every session:

| Skill | Purpose |
|-------|---------|
| `/batch <instruction>` | Parallel large-scale codebase changes via worktrees |
| `/claude-api` | Claude API/SDK reference for your project's language |
| `/debug [description]` | Enable debug logging, troubleshoot issues |
| `/loop [interval] <prompt>` | Run a prompt repeatedly on an interval |
| `/simplify [focus]` | Review changed files for reuse, quality, efficiency |

Three more bundled skills launch and verify your app (require Claude Code v2.1.145+):

| Skill | Purpose |
|-------|---------|
| `/run` | Launch and drive your app to see a change working |
| `/verify` | Build and run your app to confirm a change, without falling back to tests |
| `/run-skill-generator` | Record a per-project recipe so `/run` and `/verify` know how to build and launch |

## Skill Content Lifecycle

When a skill is invoked, the rendered `SKILL.md` content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the file on later turns - write standing instructions, not one-time steps.

Auto-compaction carries invoked skills forward within a token budget: after a summary, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens, filled from the most recently invoked skill - so older skills can be dropped after compaction. Re-invoke a skill after compaction to restore its full content.

## Permission Control

### Pre-approve tools per skill

`allowed-tools` grants permission for the listed tools while the skill is active, so Claude uses them without a prompt. It does **not** restrict which tools are available - every tool stays callable, and your permission settings still govern the rest. Accepts a space-separated string or a YAML list:

```yaml
---
name: safe-reader
description: Read files without making changes
allowed-tools: Read Grep Glob
---
```

To block a skill from a tool, add a deny rule in permission settings instead.

### Restrict Claude's skill access

In `/permissions` deny rules:
- `Skill` - disable all skills
- `Skill(deploy *)` - deny specific skill
- `Skill(commit)` - deny exact match

A few built-in commands are also reachable through the Skill tool: `/init`, `/review`, `/security-review`. Others such as `/compact` are not.

### Path-based activation

```yaml
---
name: frontend-lint
description: Lint frontend code
paths: "src/components/**/*.tsx, src/pages/**/*.tsx"
---
```

Skill only activates when working with files matching the patterns.

## Settings Overrides

`skillOverrides` controls skill visibility from settings instead of the skill's own frontmatter - useful for skills you don't want to edit (shared repo, MCP-provided). Each key is a skill name; each value is one of four states:

| Value | Listed to Claude | In `/` menu |
|-------|-----------------|-------------|
| `"on"` | Name and description | Yes |
| `"name-only"` | Name only | Yes |
| `"user-invocable-only"` | Hidden | Yes |
| `"off"` | Hidden | Hidden |

A skill absent from `skillOverrides` is treated as `"on"`. The `/skills` menu writes it to `.claude/settings.local.json` for you. Plugin skills are unaffected.

## Context Budget

Skill descriptions are loaded into context at startup. The budget scales at **1% of the model's context window**. When it overflows, the descriptions of least-used skills are dropped first; names are always kept.

Run `/doctor` to see whether the budget is overflowing and which skills are affected.

Raise the budget with the `skillListingBudgetFraction` setting (e.g. `0.02` = 2%) or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var (fixed character count). Independently, each entry's combined `description` + `when_to_use` text is capped at **1,536 characters** in the listing (configurable via `maxSkillDescriptionChars`). Set low-priority skills to `"name-only"` in `skillOverrides` to free budget.

## Extended Thinking

To enable extended thinking in a skill, include the word "ultrathink" anywhere in the skill content.

## Shell Override

For Windows PowerShell support:

```yaml
---
shell: powershell
---
```

Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`.


path: references/clawhub-publishing.md
content: # Publishing to ClawHub

ClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. It extends Anthropic's base skill spec with runtime metadata (`metadata.openclaw`), automatic moderation (3 scanners), and a CLI/API for publishing. This is the field guide for getting skills past moderation on the first try.

Sources of truth: [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md), [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md), [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md), [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md).

## What ClawHub adds to the Anthropic spec

| Concept | Anthropic spec | ClawHub addition |
|---|---|---|
| Frontmatter | `name`, `description`, optional `metadata: dict[str,str]` | `metadata.openclaw.*` runtime declarations |
| Distribution | Manual (zip / file path) | Versioned registry, semver tags, search |
| Trust | None enforced | 3-scanner moderation pipeline |
| Slug | Local filename | Globally unique slug (URL-safe, never reused) |
| License | Author choice | All skills MIT-0 (auto-applied) |

## `metadata.openclaw` schema

Use the **YAML nested form** (not the JSON-blob form). `metadata.openclaw` is the canonical key; `metadata.clawdbot` and `metadata.clawdis` are aliases - skip them.

```yaml
---
name: my-skill
description: One-line summary with triggers.
metadata:
  version: "0.1.0"
  openclaw:
    homepage: https://github.com/owner/repo/tree/main/skills/my-skill
    primaryEnv: MY_API_KEY
    requires:
      bins: [curl]
      env: [MY_API_KEY]
      config: [~/.config/my-skill/config.json]
    envVars:
      - name: MY_API_KEY
        required: true
        description: Primary credential for the upstream service.
      - name: MY_OPTIONAL_FLAG
        required: false
        description: Toggles experimental behavior.
    emoji: "🔌"
    os: [darwin, linux]
---
```

Field reference:

| Field | Type | Purpose |
|---|---|---|
| `requires.env` | `string[]` | Hard-required env vars. Skill cannot run without these. |
| `requires.bins` | `string[]` | Binaries that must all be on PATH. |
| `requires.anyBins` | `string[]` | At least one of these binaries must be present. |
| `requires.config` | `string[]` | Config file paths that must exist/be truthy. |
| `envVars[]` | `{name, required?, description?}` | Per-variable metadata. **Use this for optional env vars** with `required: false`. |
| `primaryEnv` | `string` | Main credential. Must also appear in `requires.env` or `envVars`. |
| `homepage` | `string` | Source URL. Raises trust score; ClawScan flags missing homepage. |
| `emoji` | `string` | Single emoji for UI display. |
| `os` | `string[]` | OS filter (`darwin`, `linux`, etc.). |
| `always` | `boolean` | If true, skill is always active. Use with caution - flagged for review. |
| `skillKey` | `string` | Override invocation key (rarely needed). |
| `install[]` | `array` | Auto-install hints (`brew`, `node`, `go`, `uv`, `download`). |

**Critical rule**: required env vars go under `requires.env`; optional/integration env vars go under `envVars` with `required: false`. Putting optional vars in `requires.env` will make ClawHub gate the skill behind credentials it doesn't actually need; mixing them up flags as metadata mismatch.

## Slugs and display names

- Slug regex: `^[a-z0-9][a-z0-9-]*$`. Lowercase, kebab-case.
- Default slug = folder name. Override at publish with `--slug`.
- Renaming: `clawhub skill rename <old> <new>` keeps the old slug as a redirect alias.
- Display name is set at publish via `--name`. Convention in this repo: **display name == slug** (set automatically by `scripts/prepare_skill_release.py`).
- Slugs are globally unique across all of ClawHub. If your folder name is taken, you'll need a `--slug` override.

## Install specs

Declare third-party tooling under `metadata.openclaw.install`:

```yaml
install:
  - kind: brew
    formula: jq
    bins: [jq]
  - kind: node
    package: typescript@5
    bins: [tsc]
  - kind: go
    module: github.com/user/tool@latest
    bins: [tool]
  - kind: uv
    package: ruff==0.15.12
    bins: [ruff]
```

Supported kinds: `brew`, `node`, `go`, `uv`. Validation: no shell metacharacters in package names.

## Moderation pipeline

Every publish triggers three scans. Each contributes a verdict; the worst wins.

| Scanner | Reason code prefix | What it catches |
|---|---|---|
| **VirusTotal** | `vt_*` | URL/file content reputation (known malware signatures, bad domains). |
| **ClawScan** (LLM) | `llm_suspicious` | Context-aware semantic review. Flags metadata-vs-runtime mismatch, capability overreach, undeclared credentials, internal contradictions. |
| **Static analysis** | specific codes (see below) | Pattern matching for risky literals. |

ClawScan's review dimensions: `Purpose & Capability`, `Instruction Scope`, `Install Mechanism`, `Credentials`, `Persistence & Privilege`. Each can be `ok` / `note` / `concern`. Its risk analysis uses the [OWASP Agentic Skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/) as a lens (prompt injection, tool misuse, credential exposure, unsafe execution, context poisoning, excessive agency).

To inspect: `curl -H "Authorization: Bearer <token>" https://clawhub.ai/api/v1/skills/<slug>` returns the `moderation` block with `verdict` (`clean` / `suspicious` / `malicious`), `reasonCodes[]`, `summary`, `engineVersion`.

## Reason codes catalog

| Code | Trigger | Fix |
|---|---|---|
| `suspicious.llm_suspicious` | Metadata-runtime mismatch, capability overreach, contradictions | Declare every env / bin / config referenced in the body. Add `homepage`. Resolve flag contradictions (see below). |
| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Replace with placeholders (`<USDC_MAINNET>`) + a single canonical address/key reference table. |
| `suspicious.destructive_delete_command` | Literal `rm -rf` (even in pedagogical "don't do this" context) | Reword ("force-recursive removal") or break the literal with markup. |
| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination model/endpoint and data-handling policy. May be intrinsic to design. |
| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw`. Often a metadata-mismatch echo. |
| `suspicious.vt_suspicious` | URL or filename matched VT signature | Grep all URLs/filenames in the bundle; submit each to VT; replace the offender. |

**Hard-block** (auto-hides skill, places uploader in manual moderation): install instructions that tell users to paste obfuscated shell payloads (e.g., base64-decoded `curl | bash`). Never include these.

## Capability tags (auto-derived)

ClawHub computes 9 capability tags at publish time by running deterministic regex matchers over the lowercased concatenation of slug + display name + summary + frontmatter (JSON-stringified) + README + every text file in the bundle. Source of truth: [`convex/lib/skillCapabilityTags.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/skillCapabilityTags.ts).

These tags are **not author-declared**. The only way to drop a tag is to remove every word in the bundle that triggers its regex.

| Tag | Trigger word families |
|---|---|
| `crypto` | `crypto`, `blockchain`, `defi`, `on-chain`, `wallet`, `private key`, `erc-20`, `usdc`, `eth/ethereum`, `bitcoin/btc`, `base network`, `arbitrum`, `optimism`, `polygon`, `avalanche`, `solana`, `aave`, `token balance`, `bridge`, `liquidity`, `ens`, `x402`, contextual `defi/token/coin/nft swap` patterns |
| `financial-authority` | No regex of its own - **derived** when `can-make-purchases` or `can-sign-transactions` is set (see Auto-implications) |
| `requires-wallet` | `private key`, `wallet`, `walletClient`, `sendTransaction`, `mnemonic`, `seed phrase`, `configured wallet`, `signer`, `eip-712` |
| `can-make-purchases` | `paid automatically`, `micropayments`, `process/accept/collect payments`, `make/send/authorize payments`, `pay invoices/bills/vendors`, `payment processing`, `charge cards/customers`, `buy {credits/tokens/coins/nft/subscription/plan}`, `buy/order products after user approval`, `payment checkout`, `one-click checkout` |
| `can-sign-transactions` | `sign (and submit/send/broadcast/authorize/approve) transaction(s)`, `sendTransaction`, `approval_required`, `on-chain tx/transaction`, `execute transaction`, `broadcast transaction`, `walletClient.sendTransaction` (database/SQL/internal/workflow transactions are excluded) |
| `requires-paid-service` | `payment required`, `paid subscription/plan/api required`, `requires a pro/premium/billing subscription`, `pay per call`, `costs $N`, `charged per call/request`, `account top-up/recharge`, `402 payment required` + `insufficient balance`. Negations (`no payments required`, `never requires a subscription`) are stripped before matching |
| `requires-oauth-token` | `oauth`, `oauth 2.0`, `access token`, `refresh token`, `bearer token`, `tweet.write` |
| `requires-sensitive-credentials` | `api key`/`api_key`/`api-key`, `access/refresh/bearer token`, `session/auth cookie(s)`, `private key`, `mnemonic`, `seed phrase`, `signer` |
| `posts-externally` | `post (a/this) tweet`, `reply to tweet`, `quote tweet`, `post to x/twitter`, `twitter-post`, `publish post` |

**Auto-implications** (set after the regex pass):
- `can-make-purchases` OR `can-sign-transactions` → adds `financial-authority`
- `can-sign-transactions` AND `crypto` → adds `requires-wallet`
- `requires-wallet` OR `can-sign-transactions` OR `requires-oauth-token` → adds `requires-sensitive-credentials`

Purchase or transaction-signing authority on its own no longer derives `crypto` or `requires-wallet`; non-crypto financial skills get `financial-authority` instead.

**Why this matters**: ClawScan (the LLM scanner) reads the capability tags and flags `suspicious` when a tag is set but the skill's stated purpose doesn't justify it (e.g. a fact-check skill with `can-make-purchases`). The fix is **always** content-side: find the trigger word, remove or rephrase it. Defensive scoping language (e.g., "this skill does NOT make payments") usually backfires - it adds the very trigger words it tries to disclaim.

**False-positive appeal**: when a tag is genuinely incorrect (e.g. `display=swap` matching the `\bswap\b` crypto regex) and the trigger word can't be rephrased, file an issue at [openclaw/clawhub](https://github.com/openclaw/clawhub/issues) - maintainers tighten regex patterns over time (see PR #1857 for an example fix).

## Author-declarable flags

`disable-model-invocation: true` (top-level frontmatter, not under `metadata`):
- Stops Claude from auto-invoking the skill based on prompt content. Skill only fires on explicit slash command.
- Use for explicit-invocation skills (e.g., `/review`, `/polish`).
- **Don't combine** with internal `Agent(model: "opus")` overrides in the skill body - that contradiction triggers high-confidence suspicious. Subagents inherit the parent's model anyway.

`always: true` (under `metadata.openclaw`): skill loads at every session. Combine with `homepage` and explicit credential declarations or it'll flag.

## Publishing constraints

- 50 MB total bundle size.
- Text-based files only (no binaries).
- GitHub account must be ≥ 14 days old.
- All publishes are MIT-0; no per-skill license overrides.
- Semver versions are immutable; tags (`latest`) are mutable pointers.
- No paid skills, no per-skill pricing, no paywalls.
- Publishing 5 *new* skills/hour (rate limit on first-time slugs only; updates aren't capped).

## CLI cheat-sheet

```bash
# Publish (requires existing slug for first-time + --version semver)
clawhub publish ./skills/my-skill \
  --slug my-skill \
  --name my-skill \
  --version 0.1.0 \
  --changelog "Initial release." \
  --clawscan-note "Network access is limited to the user-configured API." \
  --tags latest

# Inspect (owner-visible moderation diagnostics when logged in)
clawhub inspect my-skill --json

# Soft-delete / restore (owner reversible)
clawhub delete my-skill
clawhub undelete my-skill

# Rename (preserves redirect from old slug)
clawhub skill rename my-skill my-new-skill

# Sync all changed local skills
clawhub sync --bump patch --tags latest
```

Use `--clawscan-note "<text>"` on publish to pre-explain behavior that may look unusual (network access, native host access, provider credentials). It gives ClawScan context and is stored on the published version.

Direct moderation API (most useful for debugging suspicious flags):

```bash
TOKEN="$(jq -r .token "$HOME/Library/Application Support/clawhub/config.json")"
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://clawhub.ai/api/v1/skills/<slug> | jq .moderation
```

## Pre-publish checklist

- [ ] Frontmatter `name` matches folder name.
- [ ] `description` ≤ 1024 chars; includes trigger phrases.
- [ ] Every env var, binary, and config path referenced in SKILL.md or references is declared in `metadata.openclaw`.
- [ ] Optional env vars use `envVars` with `required: false`, not `requires.env`.
- [ ] `homepage` set.
- [ ] `metadata.version` bumped (semver, never reused).
- [ ] No instruction text contains literal `curl | bash` with base64 (hard-block).
- [ ] No internal `Agent(model: "opus")` calls in the skill body if `disable-model-invocation: true`.
- [ ] No long secret-shaped literals; addresses/keys go in a single canonical reference table with placeholders inline.
- [ ] `LICENSE.txt` present (auto-added by ClawHub publish; required for external bundles).
- [ ] Run `just check` (or equivalent linter) green.


path: references/description-guide.md
content: # Writing Effective Skill Descriptions

The `description` field is the most critical component of your skill. It determines when Claude activates your skill from potentially 100+ available skills. Get this right.

## Structure

A strong description has three parts:

1. **Capabilities** - specific things the skill does (action verbs)
2. **Triggers** - when to activate (user phrases, file types, contexts)
3. **Boundaries** - what it does NOT do (optional but useful)

## Rules

- Write in **third person**: "Processes files..." not "I help you..."
- Max **1024 characters**
- No XML angle brackets (`<` or `>`)
- Include **WHAT** + **WHEN**
- Be slightly "pushy" - Claude tends to undertrigger
- Write natural prose, not keyword dumps - Claude matches on semantic meaning, so a long "Triggers on X, Y, Z..." list adds little over a clear sentence

## Examples: Good Descriptions

### PDF Processing

```yaml
description: Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user mentions
  PDFs, forms, or document extraction.
```

Why it works: specific verbs (extract, fill, merge), concrete triggers (PDF files, forms), clear use cases.

### Excel Analysis

```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate
  charts. Use when analyzing Excel files, spreadsheets, tabular data,
  or .xlsx files.
```

Why it works: mentions specific capabilities and file types that trigger naturally.

### Git Commit Helper

```yaml
description: Generate descriptive commit messages by analyzing git diffs.
  Use when the user asks for help writing commit messages or reviewing
  staged changes.
```

Why it works: specific action (generate commit messages) with natural trigger phrases.

### Linear Sprint Planning

```yaml
description: Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions "sprint",
  "Linear tasks", "project planning", or asks to "create tickets".
```

Why it works: names the specific tool, lists capabilities, includes exact phrases.

### Frontend Design

```yaml
description: Create distinctive, production-grade frontend interfaces
  with high design quality. Use this skill when the user asks to build
  web components, pages, or applications. Generates creative, polished
  code that avoids generic AI aesthetics.
```

Why it works: describes both the capability and the quality standard.

### Brand Guidelines

```yaml
description: Applies Anthropic's official brand colors and typography
  to any sort of artifact that may benefit from having Anthropic's
  look-and-feel. Use it when brand colors or style guidelines, visual
  formatting, or company design standards apply.
```

Why it works: specific about what data it provides, clear about activation context.

## Examples: Bad Descriptions

### Too Vague

```yaml
# BAD
description: Helps with documents.
# Why: no specific capabilities, no triggers, matches everything and nothing
```

### Missing Triggers

```yaml
# BAD
description: Creates sophisticated multi-page documentation systems.
# Why: describes capability but not WHEN to use it
```

### Too Technical

```yaml
# BAD
description: Implements the Project entity model with hierarchical
  relationships.
# Why: no user-facing triggers, overly technical
```

### Wrong Point of View

```yaml
# BAD
description: I can help you process Excel files and create reports.
# Why: first person ("I") causes discovery problems in system prompt

# ALSO BAD
description: You can use this to process Excel files.
# Why: second person ("You") also problematic
```

## Adding Negative Triggers

When your skill overtriggers (loads for irrelevant queries), add boundaries:

```yaml
description: Advanced data analysis for CSV files. Use for statistical
  modeling, regression, clustering. Do NOT use for simple data
  exploration (use data-viz skill instead).
```

```yaml
description: PayFlow payment processing for e-commerce. Use specifically
  for online payment workflows, not for general financial queries.
```

## Descriptions for Manually-Invoked Skills

A skill with `disable-model-invocation: true` is never auto-triggered - Claude only runs it when the user types `/name`. Its description shows in the `/` menu only, so trigger phrases and negative triggers do nothing for it. Write a plain one-line summary of what the command does and skip the trigger-tuning.

## Description for MCP-Enhanced Skills

When your skill works with an MCP server, mention both the tool and the workflow:

```yaml
description: Manages Linear project workflows including sprint planning,
  task creation, and status tracking via MCP. Use when user mentions
  "sprint", "Linear tasks", or asks to "create tickets". Requires
  Linear MCP server to be connected.
```

## Debugging Descriptions

Ask Claude: "When would you use the [skill-name] skill?"

Claude will quote the description back. Check:
- Does it mention the capabilities you expect?
- Does it include the trigger phrases users would actually say?
- Does it mention relevant file types?
- Is it specific enough to distinguish from similar skills?

Adjust based on what's missing. Iterate until Claude correctly identifies when to use your skill.

## Undertriggering vs Overtriggering

| Signal | Problem | Fix |
|--------|---------|-----|
| Skill doesn't load when it should | Undertriggering | Add more use cases, trigger phrases, file types |
| Users manually enabling it | Undertriggering | Broaden description, add synonyms |
| Skill loads for unrelated queries | Overtriggering | Add negative triggers, be more specific |
| Users disabling it | Overtriggering | Narrow scope, clarify boundaries |


path: references/patterns.md
content: # Skill Patterns and Workflows

Advanced patterns for structuring skills, drawn from Anthropic's official examples and early adopter experience.

## Contents

- Choosing your approach (problem-first vs tool-first)
- Pattern 1: Sequential workflow orchestration
- Pattern 2: Multi-MCP coordination
- Pattern 3: Iterative refinement with feedback loops
- Pattern 4: Context-aware tool selection
- Pattern 5: Domain-specific intelligence
- Pattern 6: Plan-validate-execute
- Pattern 7: Template pattern
- Pattern 8: Examples pattern (input/output pairs)
- Progressive disclosure patterns
- Skills + MCP integration
- Skills + Subagents integration
- Developing skills with Claude (Claude A / Claude B)

## Choosing Your Approach

### Problem-First

User describes an outcome; the skill orchestrates the right tools:

```
"I need to set up a project workspace"
-> Skill calls create_project, add_members, configure_settings
```

### Tool-First

User has a tool connected; the skill teaches best practices:

```
"I have Notion MCP connected"
-> Skill provides optimal workflows and conventions
```

Most skills lean one direction. Know which framing fits your use case.

## Pattern 1: Sequential Workflow Orchestration

Use when: multi-step processes must follow a specific order.

```markdown
## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template
```

Key techniques:
- Explicit step ordering
- Dependencies between steps clearly stated
- Validation at each stage
- Rollback instructions for failures

## Pattern 2: Multi-MCP Coordination

Use when: workflows span multiple services.

```markdown
## Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

## Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

## Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

## Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references
```

Key techniques:
- Clear phase separation
- Data passing between MCPs explicitly described
- Validation before moving to next phase
- MCP tool names use `ServerName:tool_name` format

## Pattern 3: Iterative Refinement

Use when: output quality improves with iteration.

```markdown
## Iterative Report Creation

### Initial Draft
1. Fetch data via MCP
2. Generate first draft
3. Save to temporary file

### Quality Check
Run: `python scripts/check_report.py`
Identify issues:
- Missing sections
- Inconsistent formatting
- Data validation errors

### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version
```

The feedback loop (`validate -> fix -> re-validate`) greatly improves output quality.

## Pattern 4: Context-Aware Tool Selection

Use when: same outcome, different tools depending on context.

```markdown
## Smart File Storage

### Decision Tree
1. Check file type and size
2. Determine best storage:
   - Large files (>10MB): cloud storage MCP
   - Collaborative docs: Notion/Docs MCP
   - Code files: GitHub MCP
   - Temporary files: local storage

### Execute Storage
Based on decision, call appropriate MCP tool.

### Provide Context
Explain to user why that storage was chosen.
```

## Pattern 5: Domain-Specific Intelligence

Use when: your skill adds specialized knowledge beyond tool access.

```markdown
## Payment Processing with Compliance

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
  - Process transaction
ELSE:
  - Flag for review
  - Create compliance case

### Audit Trail
- Log all compliance checks
- Record processing decisions
```

## Pattern 6: Plan-Validate-Execute

Use when: complex operations where mistakes are costly.

```markdown
## Batch Update Workflow

### Step 1: Analyze
Run: `python scripts/analyze.py input.pdf`
Output: fields.json

### Step 2: Create Plan
Edit fields.json with intended changes

### Step 3: Validate Plan
Run: `python scripts/validate.py fields.json`
Fix any errors before proceeding.
Verbose error messages help: "Field 'signature_date' not found.
Available fields: customer_name, order_total, signature_date_signed"

### Step 4: Execute
Run: `python scripts/apply.py input.pdf fields.json output.pdf`

### Step 5: Verify
Run: `python scripts/verify.py output.pdf`
If verification fails, return to Step 2.
```

Why this works:
- Catches errors before changes are applied
- Machine-verifiable with scripts
- Reversible planning phase
- Clear debugging with specific error messages

## Pattern 7: Template Pattern

Provide templates for output format. Match strictness to needs:

### Strict (API responses, data formats)

```markdown
ALWAYS use this exact structure:

# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with data
- Finding 2 with data

## Recommendations
1. Specific action
2. Specific action
```

### Flexible (when adaptation is useful)

```markdown
Sensible default format - adjust as needed:

# [Title]
## Summary
## Findings
## Recommendations
```

## Pattern 8: Examples Pattern

For output-quality-dependent skills, provide input/output pairs:

```markdown
## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Examples communicate desired style better than descriptions alone.

## Progressive Disclosure Patterns

### High-Level Guide with References

```
SKILL.md:
  Quick start + overview
  Links to: FORMS.md, REFERENCE.md, EXAMPLES.md
```

Claude loads each file only when needed.

### Domain-Specific Organization

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing)
    ├── sales.md (pipeline, accounts)
    └── product.md (API usage, features)
```

When user asks about revenue, Claude reads only finance.md.

### Conditional Details

```markdown
## Creating documents
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
```

## Skills + MCP Integration

MCP provides **tool access** (what Claude can do). Skills provide **workflow knowledge** (how Claude should do it).

Without skills: users connect MCP but don't know optimal workflows, each conversation starts from scratch, inconsistent results.

With skills: pre-built workflows activate automatically, consistent tool usage, best practices embedded.

When referencing MCP tools in skills, use fully qualified names:

```markdown
Use the BigQuery:bigquery_schema tool to retrieve schemas.
Use the GitHub:create_issue tool to create issues.
```

## Skills + Subagents Integration

Skills and subagents complement each other:

- **Skills**: portable expertise any agent can load
- **Subagents**: independent task execution with own context

Use together: a code-review subagent loads language-specific best practice skills.

In Claude Code, use `context: fork` in frontmatter to run a skill in an isolated subagent:

```yaml
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with file references
```

## Developing Skills with Claude (Claude A / Claude B)

The most effective way to build a skill is with Claude itself, in two roles:

- **Claude A** - helps you design and refine the skill (it understands the skill format and what agents need)
- **Claude B** - a fresh instance with the skill loaded, used to test it on real tasks

Workflow:

1. Complete a task with Claude A using normal prompting; notice what context you repeatedly supply.
2. Ask Claude A to capture that as a skill.
3. Review for conciseness and information architecture.
4. Test with Claude B on related tasks - observe where it struggles or misses references.
5. Bring specific observations back to Claude A ("Claude B forgot to filter test accounts") and refine.
6. Repeat the observe-refine-test loop with real usage, not invented scenarios.

Iterate on observed behavior, not assumptions.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)