zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:05:19 +08:00
commit 09fec2555b
96 changed files with 24269 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
skills/managing-skills/LICENSE.txt Normal file
View File

@@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://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
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

408
skills/managing-skills/SKILL.md Normal file
View File

@@ -0,0 +1,408 @@
---
name: Managing Skills
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. Adapted for Warren's system with snippet integration.
license: Complete terms in LICENSE.txt
---
# Managing Skills
**Attribution:** This skill is based on Anthropic's `skill-creator` from the [anthropic-agent-skills](https://github.com/anthropics/anthropic-agent-skills) repository, licensed under Apache License 2.0. This derivative work includes modifications for Warren's plugin system and snippet integration.
**Copyright:** Original work Copyright Anthropic. Modifications Copyright 2025 Warren Zhu.
**License:** Apache License 2.0 (see LICENSE.txt for complete terms)
---
## Warren's System Configuration
**Default Skill Location:**
All new skills for Warren's system should be created in:
```
~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/skills/
```
**Other Skill Locations:**
- Personal: `~/.claude/skills/` (individual workflows)
- Project: `.claude/skills/` (team workflows, commit to git)
- Plugin: Plugin's `skills/` directory (distributable)
---
## About Skills
Skills are modular, self-contained packages that extend Claude's capabilities by providing
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
equipped with procedural knowledge that no model can fully possess.
### What Skills Provide
1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
### Anatomy of a Skill
Every skill consists of a required SKILL.md file and optional bundled resources:
```
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
```
#### SKILL.md (required)
**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
**Critical Format Rule:** Do NOT include overview sections or "When to Use This Skill" sections in the SKILL.md body. This information belongs ONLY in the YAML frontmatter description. The body should contain ONLY procedural instructions on how to use the skill.
**Incorrect format:**
```markdown
---
name: example
description: Brief description
---
# Example Skill Title
Overview paragraph explaining what the skill does.
## When to Use This Skill
- Use case 1
- Use case 2
## How to Use
Instructions here...
```
**Correct format:**
```markdown
---
name: example
description: Detailed description including what the skill does, when to use it (use case 1, use case 2, etc.), and what it provides. Use when working with X, Y, and Z operations.
---
## How to Use
Instructions here (no overview, no "when to use" section)...
```
#### Bundled Resources (optional)
##### Scripts (`scripts/`)
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
##### References (`references/`)
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
- **When to include**: For documentation that Claude should reference while working
- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
##### Assets (`assets/`)
Files not intended to be loaded into context, but rather used within the output Claude produces.
- **When to include**: When the skill needs files that will be used in the final output
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
### Progressive Disclosure Design Principle
Skills use a three-level loading system to manage context efficiently:
1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by Claude (Unlimited*)
*Unlimited because scripts can be executed without reading into context window.
## Skill Creation Process
To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
### Step 1: Understanding the Skill with Concrete Examples
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
- "Can you give some examples of how this skill would be used?"
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
- "What would a user say that should trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
### Step 2: Planning the Reusable Skill Contents
To turn concrete examples into an effective skill, analyze each example by:
1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
1. Rotating a PDF requires re-writing the same code each time
2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
### Step 3: Initializing the Skill
At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
**For Warren's system**, create the skill directory manually in the default location:
```bash
# Create skill directory in Warren's plugin
mkdir -p ~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/skills/my-skill
# Create subdirectories as needed
mkdir -p ~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/skills/my-skill/scripts
mkdir -p ~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/skills/my-skill/references
mkdir -p ~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/skills/my-skill/assets
```
**If using Anthropic's init_skill.py script** (for other systems):
```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```
The script creates a template with proper frontmatter and example directories.
After initialization, customize or remove the generated SKILL.md and example files as needed.
### Step 4: Edit the Skill
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
#### Start with Reusable Skill Contents
To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
#### Update SKILL.md
**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
**Content Organization:**
1. **YAML Frontmatter (required):**
- `name`: Skill identifier
- `description`: Comprehensive description that includes:
- What the skill does
- When to use it (all use cases)
- What it provides (features, capabilities)
- Any pre-configured elements
2. **Markdown Body (required):**
- **Start directly with procedural sections** (e.g., "## Environment Setup", "## Helper Script Usage")
- **Do NOT include:**
- Title headers repeating the skill name
- Overview/introduction paragraphs
- "When to Use This Skill" sections
- "What This Skill Provides" sections
- **DO include:**
- Setup instructions
- Usage examples
- Common operations
- Workflow guidelines
- References to bundled resources
**Example structure:**
```markdown
---
name: my-skill
description: [Complete description with all use cases and features]
---
## Environment Setup
[Setup instructions]
## Using the Helper Script
[How to use scripts/]
## Common Operations
[Examples and patterns]
```
All reusable skill contents (scripts, references, assets) should be referenced in the body so Claude knows how to use them.
### Step 5: Packaging a Skill
Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
```bash
scripts/package_skill.py <path/to/skill-folder>
```
Optional output directory specification:
```bash
scripts/package_skill.py <path/to/skill-folder> ./dist
```
The packaging script will:
1. **Validate** the skill automatically, checking:
- YAML frontmatter format and required fields
- Skill naming conventions and directory structure
- Description completeness and quality
- File organization and resource references
2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
**Note:** For Warren's system, skills are typically not packaged as zip files but remain in place within the plugin directory structure.
### Step 6: Iterate
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
**Iteration workflow:**
1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again
---
## Snippet Integration (Warren's System)
Skills in Warren's system can be enhanced with **snippet integration** for instant keyword activation. This allows skills to be triggered by specific keywords in user prompts, providing explicit control over when a skill loads.
### When to Add Snippet Integration
Add snippet integration when:
- Skill needs instant activation by specific keyword (e.g., "USE SKILL_NAME")
- Skill is used frequently in specific contexts
- Want to bypass automatic skill discovery and ensure deterministic loading
### How to Add Snippet Integration
1. **Read the managing-snippets skill** for detailed instructions on snippet management
2. **Add entry to config.local.json** at:
```
~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/config.local.json
```
3. **Example snippet pattern:**
```json
{
"hooks": {
"user-prompt-submit": {
"enabled": true,
"order": 0,
"patterns": [
{
"regex": "\\bUSE MY-SKILL\\b",
"command": "~/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/scripts/read-skill.sh 'my-skill'"
}
]
}
}
}
```
4. **Test the snippet:**
- Type "USE MY-SKILL" in a prompt
- Verify the skill content loads
5. **Restart Claude Code** to activate the snippet
### Snippet vs. Automatic Discovery
**Automatic Discovery:**
- Claude decides when to load skill based on description
- More flexible, adapts to varied user phrasings
- Relies on good description metadata
**Snippet Activation:**
- User explicitly triggers skill with keyword
- Deterministic loading every time
- Useful for workflows where skill should always be active
**Recommendation:** Use both approaches together. Let automatic discovery handle most cases, and provide snippet keywords for power users who want explicit control.
---
## CHANGELOG
### Modified 2025-10-26 by Warren Zhu
**Changes made to derivative work:**
1. **Added Warren's system configuration** (Section: "Warren's System Configuration")
- Specified default skill location for Warren's plugin
- Listed alternative skill locations
2. **Modified Step 3: Initializing the Skill**
- Added Warren-specific manual directory creation commands
- Noted that Anthropic's init_skill.py is for other systems
3. **Modified Step 5: Packaging a Skill**
- Added note that Warren's system doesn't typically use zip packaging
- Skills remain in place within plugin directory
4. **Added Section: "Snippet Integration (Warren's System)"**
- Explained when to add snippet integration
- Provided instructions for adding snippets
- Documented snippet vs. automatic discovery tradeoffs
- Referenced managing-snippets skill for details
5. **Updated YAML frontmatter**
- Modified description to mention Warren's system and snippet integration
- Renamed skill from "skill-creator" to "Managing Skills"
6. **Added attribution, copyright, and license notices**
- Acknowledged Anthropic as original author
- Included Apache License 2.0 reference
**Original work attribution:**
- Source: https://github.com/anthropics/anthropic-agent-skills/tree/main/skill-creator
- License: Apache License 2.0
- Copyright: Anthropic
All other content remains unchanged from the original Anthropic skill-creator.

422
skills/managing-skills/creating.md Normal file
View File

@@ -0,0 +1,422 @@
# Creating Skills
Step-by-step guidance for creating new Agent Skills in Claude Code.
## Quick Start
### 1. Choose Skill Location
**Personal Skills** (`~/.claude/skills/`):
- Individual workflows
- Experimental skills
- Personal productivity tools
**Project Skills** (`.claude/skills/`):
- Team workflows
- Project-specific expertise
- Shared utilities (commit to git)
**Plugin Skills** (plugin's `skills/` directory):
- Distributable skills
- Part of a plugin package
- Automatically available when plugin installed
### 2. Create Skill Directory
```bash
# Personal
mkdir -p ~/.claude/skills/my-skill-name
# Project
mkdir -p .claude/skills/my-skill-name
# Plugin
mkdir -p path/to/plugin/skills/my-skill-name
```
### 3. Create SKILL.md
Minimum required structure:
```yaml
---
name: Your Skill Name
description: What it does and when to use it (include trigger terms)
---
# Your Skill Name
## Instructions
Provide clear, step-by-step guidance.
## Examples
Show concrete examples of using this skill.
```
## Writing Effective Descriptions
The `description` field is critical for skill discovery.
### Requirements
- **Write in third person** (goes into system prompt)
- **Include WHAT the skill does**
- **Include WHEN to use it**
- **Add specific trigger terms** users would mention
- **Maximum 1024 characters**
### Good Examples
**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.
```
**Excel Analysis**:
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**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.
```
### Bad Examples
```yaml
description: Helps with documents # Too vague
description: Processes data # Not specific enough
description: Does stuff with files # No trigger terms
```
## Skill Structure Guidelines
### Keep Skills Focused
One skill = one capability
**Good** (focused):
- "PDF form filling"
- "Excel data analysis"
- "Git commit messages"
**Too broad** (split into multiple skills):
- "Document processing"
- "Data tools"
- "File operations"
### Use Progressive Disclosure
Keep SKILL.md under 500 lines. Split content into separate files.
**Pattern**:
```
my-skill/
├── SKILL.md # Main instructions (< 500 lines)
├── reference.md # Detailed API docs
├── examples.md # Usage examples
└── scripts/
└── helper.py # Utility scripts
```
**In SKILL.md**:
```markdown
# My Skill
## Quick Start
[Brief overview and common usage]
## Advanced Features
For complete API documentation, see [reference.md](reference.md).
For usage patterns, see [examples.md](examples.md).
```
Claude loads additional files only when needed.
### Avoid Deeply Nested References
**Keep references one level deep from SKILL.md**.
**Bad** (too deep):
```markdown
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
```
**Good** (one level):
```markdown
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```
### Structure Longer Reference Files
For reference files >100 lines, include a table of contents:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and Setup
...
## Core Methods
...
```
## Content Guidelines
### Be Concise
**Challenge each piece of information**:
- Does Claude really need this explanation?
- Can I assume Claude knows this?
- Does this justify its token cost?
**Good** (concise):
````markdown
## Extract PDF Text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad** (too verbose):
```markdown
## Extract PDF Text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
### Use Consistent Terminology
Choose one term and use it throughout:
**Good**:
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad**:
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
### Avoid Time-Sensitive Information
**Bad**:
```markdown
If you're doing this before August 2025, use the old API.
```
**Good**:
```markdown
## Current Method
Use the v2 API: `api.example.com/v2/messages`
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
## Tool Restrictions (Optional)
Use `allowed-tools` to limit which tools Claude can use when the skill is active:
```yaml
---
name: Safe File Reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---
# Safe File Reader
This skill provides read-only file access.
## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern
```
When this skill is active, Claude can only use the specified tools without asking permission.
**Use cases**:
- Read-only skills that shouldn't modify files
- Limited scope skills (e.g., only data analysis, no file writing)
- Security-sensitive workflows
## Testing Your Skill
### 1. Test by Asking Relevant Questions
Ask questions that match your description:
**Example**: If your description mentions "PDF files":
```
Can you help me extract text from this PDF?
```
Claude should autonomously use your skill.
### 2. Check Skill Discovery
**List all skills**:
Ask Claude: "What skills are available?"
**Verify file structure**:
```bash
# Personal
ls ~/.claude/skills/my-skill/SKILL.md
# Project
ls .claude/skills/my-skill/SKILL.md
```
### 3. Debug Common Issues
**Skill doesn't activate**:
- Make description more specific
- Include trigger terms users would mention
- Add "when to use" guidance
**YAML syntax errors**:
```bash
cat SKILL.md | head -n 10
```
Ensure:
- Opening `---` on line 1
- Closing `---` before markdown
- Valid YAML (no tabs, correct indentation)
**Wrong location**:
Check skill is in correct directory with SKILL.md file.
## Complete Examples
### Simple Skill (Single File)
```
commit-helper/
└── SKILL.md
```
**SKILL.md**:
```yaml
---
name: Generating Commit Messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---
# Generating Commit Messages
## Instructions
1. Run `git diff --staged` to see changes
2. Suggest a commit message with:
- Summary under 50 characters
- Detailed description
- Affected components
## Best Practices
- Use present tense
- Explain what and why, not how
```
### Multi-File Skill
```
pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
├── fill_form.py
└── validate.py
```
**SKILL.md**:
````yaml
---
name: PDF Processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---
# PDF Processing
## Quick Start
Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
## Requirements
Install packages:
```bash
pip install pypdf pdfplumber
```
````
## Best Practices Summary
✅ **Do**:
- Write descriptions in third person
- Include trigger terms in description
- Keep SKILL.md under 500 lines
- Use progressive disclosure for large content
- Be concise - assume Claude is smart
- Use consistent terminology
- Test with relevant questions
- Keep skills focused (one capability per skill)
❌ **Don't**:
- Write vague descriptions
- Include time-sensitive information
- Nest references more than one level deep
- Over-explain things Claude already knows
- Create overly broad skills
- Use inconsistent terminology

385
skills/managing-skills/deleting.md Normal file
View File

@@ -0,0 +1,385 @@
# Deleting Skills
Guidance for safely removing Agent Skills from Claude Code.
## Quick Deletion Process
### 1. Locate the Skill
```bash
# Personal skills
ls ~/.claude/skills/
# Project skills
ls .claude/skills/
# Find specific skill
find ~/.claude/skills -name "SKILL.md" -path "*/my-skill/*"
```
### 2. Create Backup (Recommended)
Before deleting, create a backup:
```bash
# Backup entire skill directory
cp -r ~/.claude/skills/my-skill ~/.claude/skills/my-skill.backup
# Or backup to a dedicated location
cp -r ~/.claude/skills/my-skill ~/skill-backups/my-skill-$(date +%Y%m%d)
```
### 3. Delete the Skill
```bash
# Personal skill
rm -rf ~/.claude/skills/my-skill
# Project skill
rm -rf .claude/skills/my-skill
```
### 4. Verify Removal
Restart Claude Code and verify the skill is no longer available:
Ask Claude: "What skills are available?"
## Deletion Scenarios
### Delete Personal Skill
```bash
# Check it exists
ls ~/.claude/skills/my-skill/SKILL.md
# Backup
cp -r ~/.claude/skills/my-skill ~/.claude/skills/my-skill.backup
# Delete
rm -rf ~/.claude/skills/my-skill
# Verify
ls ~/.claude/skills/
```
No restart needed for personal skills if Claude Code wasn't using them.
### Delete Project Skill
For skills in `.claude/skills/` that are committed to git:
```bash
# Backup first
cp -r .claude/skills/my-skill ~/skill-backups/my-skill-backup
# Remove from git
git rm -rf .claude/skills/my-skill
# Commit
git commit -m "Remove my-skill: no longer needed"
# Push
git push
```
**Important**: Notify team members so they can pull the changes and restart Claude Code.
### Delete Plugin Skill
Plugin skills are managed by the plugin system. To remove:
**Option 1: Disable the plugin**
```
/plugin disable plugin-name@marketplace-name
```
**Option 2: Uninstall the plugin**
```
/plugin uninstall plugin-name@marketplace-name
```
You cannot delete individual skills from plugins. To modify plugin skills, fork the plugin or contact the plugin author.
## Bulk Deletion
### Delete Multiple Personal Skills
```bash
# List all personal skills
ls ~/.claude/skills/
# Backup all before deletion
cp -r ~/.claude/skills ~/skill-backups/all-skills-$(date +%Y%m%d)
# Delete specific skills
rm -rf ~/.claude/skills/skill1
rm -rf ~/.claude/skills/skill2
rm -rf ~/.claude/skills/skill3
```
### Delete All Unused Skills
```bash
# Backup first
cp -r ~/.claude/skills ~/skill-backups/all-skills-$(date +%Y%m%d)
# Review each skill before deleting
for skill in ~/.claude/skills/*; do
echo "Skill: $(basename $skill)"
echo "Description:"
head -n 10 "$skill/SKILL.md"
read -p "Delete this skill? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
rm -rf "$skill"
echo "Deleted: $(basename $skill)"
fi
done
```
## Backup Strategies
### Before Major Cleanup
Create a timestamped backup of all skills:
```bash
# Backup all personal skills
tar -czf ~/skill-backups/personal-skills-$(date +%Y%m%d-%H%M%S).tar.gz \
-C ~ .claude/skills
# Backup all project skills (from project root)
tar -czf ~/skill-backups/project-skills-$(date +%Y%m%d-%H%M%S).tar.gz \
.claude/skills
```
### Restore from Backup
```bash
# Restore all personal skills
tar -xzf ~/skill-backups/personal-skills-20251016-143022.tar.gz \
-C ~
# Restore specific skill
cp -r ~/skill-backups/my-skill-20251016 ~/.claude/skills/my-skill
```
## Version Control Best Practices
### For Project Skills
When deleting project skills from git repositories:
```bash
# Create feature branch
git checkout -b remove-unused-skills
# Remove skill
git rm -rf .claude/skills/old-skill
# Commit with explanation
git commit -m "Remove old-skill: replaced by new-skill
The old-skill has been superseded by new-skill which provides
better performance and additional features.
Team members should:
1. Pull this change
2. Restart Claude Code
3. The skill will no longer be available"
# Push and create PR
git push origin remove-unused-skills
```
### Document Removal
Update project documentation:
```markdown
# Changelog
## 2025-10-16
### Removed
- **old-skill**: Replaced by new-skill. See migration guide below.
### Migration Guide
If you were using old-skill:
1. Update your workflows to use new-skill instead
2. Key differences: [list changes]
3. See examples: [link to new-skill examples]
```
## Common Deletion Scenarios
### Skill No Longer Needed
```bash
# Simple removal
rm -rf ~/.claude/skills/deprecated-skill
```
### Skill Replaced by Better Version
```bash
# Backup old version (might need reference)
cp -r ~/.claude/skills/old-skill ~/skill-backups/old-skill-reference
# Delete old version
rm -rf ~/.claude/skills/old-skill
# The new version is already in place
ls ~/.claude/skills/new-skill
```
### Skill Conflicts with Another
If two skills activate on similar triggers:
```bash
# Review both skills
cat ~/.claude/skills/skill-a/SKILL.md | head -n 10
cat ~/.claude/skills/skill-b/SKILL.md | head -n 10
# Decide which to keep (usually the more specific one)
# Delete the less useful one
rm -rf ~/.claude/skills/skill-b
```
### Experimental Skill Didn't Work Out
```bash
# No backup needed for failed experiments
rm -rf ~/.claude/skills/experiment-skill
```
## Safety Checks
### Before Deleting, Ask:
1. **Is this skill used by others?**
- For project skills, check with team
- For personal skills, just you
2. **Is there a migration path?**
- If replacing, document new approach
- If removing, explain alternatives
3. **Have I backed it up?**
- Can I restore if needed?
- Do I have the content archived?
4. **Will this break workflows?**
- Check dependencies
- Update documentation
- Notify affected users
### Validation Checklist
Before deleting a project skill:
- [ ] Created backup
- [ ] Checked for dependents (other skills referencing this one)
- [ ] Notified team members
- [ ] Updated documentation
- [ ] Committed to version control with clear message
- [ ] Verified skill is not critical to current workflows
## Troubleshooting
### Skill Still Appears After Deletion
**Problem**: Deleted skill still shows up in available skills
**Solution**: Restart Claude Code to refresh skill registry
### Cannot Delete (Permission Denied)
```bash
# Check permissions
ls -la ~/.claude/skills/my-skill/
# Fix permissions if needed
chmod -R u+w ~/.claude/skills/my-skill/
# Then delete
rm -rf ~/.claude/skills/my-skill
```
### Accidentally Deleted Important Skill
**If you have a backup**:
```bash
# Restore from backup
cp -r ~/skill-backups/my-skill ~/.claude/skills/my-skill
# Restart Claude Code
```
**If no backup**:
- Check git history (for project skills)
- Check Time Machine or system backups
- Recreate from memory or documentation
### Team Member Still Has Deleted Skill
**For project skills**:
```bash
# Team member should pull latest changes
git pull
# Remove any local-only changes
rm -rf .claude/skills/deleted-skill
# Restart Claude Code
```
## Post-Deletion Cleanup
### Verify Skill List
After deletion, verify skills are as expected:
Ask Claude: "What skills are available?"
Or check filesystem:
```bash
# Personal skills
ls ~/.claude/skills/
# Project skills
ls .claude/skills/
```
### Update Documentation
If maintaining skill documentation:
```markdown
# Available Skills
## Active Skills
- skill-a: Description
- skill-b: Description
## Deprecated Skills
- ~~old-skill~~: Removed 2025-10-16, replaced by new-skill
```
### Clean Up References
Check for references to deleted skills in:
- Documentation files
- README files
- Other skills that might reference it
- Workflow documentation
```bash
# Find references
grep -r "old-skill" .claude/
grep -r "old-skill" docs/
```

424
skills/managing-skills/reading.md Normal file
View File

@@ -0,0 +1,424 @@
# Reading Skills
Guidance for listing, viewing, and inspecting Agent Skills in Claude Code.
## Quick Reference
### List All Available Skills
Ask Claude:
```
What skills are available?
```
or
```
List all available skills
```
Claude will show all skills from:
- Personal skills (`~/.claude/skills/`)
- Project skills (`.claude/skills/`)
- Plugin skills (from installed plugins)
### View Specific Skill
```bash
# Personal skill
cat ~/.claude/skills/my-skill/SKILL.md
# Project skill
cat .claude/skills/my-skill/SKILL.md
# Open in editor
code ~/.claude/skills/my-skill/SKILL.md
```
## Filesystem Commands
### List Personal Skills
```bash
# List all personal skills
ls ~/.claude/skills/
# List with details
ls -la ~/.claude/skills/
# Show skill names only
ls -1 ~/.claude/skills/
```
### List Project Skills
```bash
# From project root
ls .claude/skills/
# Find all project skills recursively
find . -path "*/.claude/skills/*/SKILL.md"
```
### View Skill Metadata
Extract name and description from YAML frontmatter:
```bash
# View frontmatter
head -n 10 ~/.claude/skills/my-skill/SKILL.md
# Extract just description
grep "description:" ~/.claude/skills/my-skill/SKILL.md
```
### Check Skill Structure
```bash
# List all files in skill directory
ls -la ~/.claude/skills/my-skill/
# Show directory tree
tree ~/.claude/skills/my-skill/
# Or without tree command
find ~/.claude/skills/my-skill/ -type f
```
## Inspection Patterns
### View Complete Skill Content
```bash
# View entire SKILL.md
cat ~/.claude/skills/my-skill/SKILL.md
# View with pagination
less ~/.claude/skills/my-skill/SKILL.md
# View with line numbers
cat -n ~/.claude/skills/my-skill/SKILL.md
```
### View Skill Supporting Files
```bash
# List all markdown files
ls ~/.claude/skills/my-skill/*.md
# View reference file
cat ~/.claude/skills/my-skill/reference.md
# View examples
cat ~/.claude/skills/my-skill/examples.md
```
### Search Within Skills
```bash
# Search for keyword in specific skill
grep -r "PDF" ~/.claude/skills/pdf-processing/
# Search across all personal skills
grep -r "authentication" ~/.claude/skills/
# Case-insensitive search
grep -ri "docker" ~/.claude/skills/
```
### Check Skill Size
```bash
# Size of SKILL.md
wc -l ~/.claude/skills/my-skill/SKILL.md
# Total size of skill directory
du -sh ~/.claude/skills/my-skill/
# Detailed size breakdown
du -h ~/.claude/skills/my-skill/*
```
## Finding Skills
### By Name Pattern
```bash
# Find skills with "pdf" in name
ls ~/.claude/skills/ | grep -i pdf
# Find all skills with "processing" in name
find ~/.claude/skills/ -type d -name "*processing*"
```
### By Description Content
```bash
# Find skills mentioning "Excel"
grep -l "Excel" ~/.claude/skills/*/SKILL.md
# Find skills with "API" in description
grep "description:.*API" ~/.claude/skills/*/SKILL.md
```
### By Trigger Terms
```bash
# Find which skill handles "docker"
for skill in ~/.claude/skills/*/SKILL.md; do
if grep -qi "docker" "$skill"; then
echo "Found in: $(dirname $skill)"
grep "description:" "$skill"
fi
done
```
## Understanding Skill Structure
### Check if Skill Has allowed-tools
```bash
# Check frontmatter for allowed-tools
head -n 15 ~/.claude/skills/my-skill/SKILL.md | grep "allowed-tools"
```
If present, the skill restricts which tools Claude can use.
### Identify Progressive Disclosure
```bash
# Check if skill references other files
grep -E "\[.*\]\(.*\.md\)" ~/.claude/skills/my-skill/SKILL.md
# List referenced files
ls ~/.claude/skills/my-skill/*.md
```
Skills with multiple .md files use progressive disclosure.
### Check for Scripts
```bash
# Check if skill has scripts
ls ~/.claude/skills/my-skill/scripts/
# Check for templates
ls ~/.claude/skills/my-skill/templates/
```
## Comparing Skills
### Compare Two Skill Descriptions
```bash
# View both descriptions
echo "=== Skill A ==="
head -n 10 ~/.claude/skills/skill-a/SKILL.md
echo "=== Skill B ==="
head -n 10 ~/.claude/skills/skill-b/SKILL.md
```
### Find Overlapping Skills
```bash
# Check if two skills have similar descriptions
skill_a_desc=$(grep "description:" ~/.claude/skills/skill-a/SKILL.md)
skill_b_desc=$(grep "description:" ~/.claude/skills/skill-b/SKILL.md)
echo "Skill A: $skill_a_desc"
echo "Skill B: $skill_b_desc"
```
If descriptions overlap significantly, consider consolidating.
### Diff Two Skills
```bash
# Compare skill structures
diff ~/.claude/skills/skill-a/SKILL.md ~/.claude/skills/skill-b/SKILL.md
# Or use a better diff tool
code --diff ~/.claude/skills/skill-a/SKILL.md ~/.claude/skills/skill-b/SKILL.md
```
## Validation Checks
### Verify YAML Frontmatter
```bash
# Check frontmatter syntax
head -n 15 ~/.claude/skills/my-skill/SKILL.md
# Verify required fields present
head -n 10 ~/.claude/skills/my-skill/SKILL.md | grep -E "(name:|description:)"
```
Required fields:
- `name:` - Skill name
- `description:` - What it does and when to use it
### Check File Existence
```bash
# Verify SKILL.md exists
test -f ~/.claude/skills/my-skill/SKILL.md && echo "✓ SKILL.md exists" || echo "✗ SKILL.md missing"
# Check for broken references
for ref in $(grep -oE "\[.*\]\((.*\.md)\)" ~/.claude/skills/my-skill/SKILL.md | grep -oE "\(.*\.md\)" | tr -d '()'); do
if [ -f "~/.claude/skills/my-skill/$ref" ]; then
echo "✓ $ref exists"
else
echo "✗ $ref missing"
fi
done
```
### Validate Description Length
```bash
# Check description character count
desc=$(grep "description:" ~/.claude/skills/my-skill/SKILL.md | cut -d':' -f2-)
echo "Description length: ${#desc} characters (max 1024)"
if [ ${#desc} -gt 1024 ]; then
echo "⚠️ Description too long!"
fi
```
## Organizing Skill Information
### Create Skill Inventory
```bash
# Generate list of all skills with descriptions
for skill in ~/.claude/skills/*/SKILL.md; do
skill_name=$(dirname $skill | xargs basename)
description=$(grep "description:" "$skill" | cut -d':' -f2-)
echo "- **$skill_name**: $description"
done
```
### Export Skill Documentation
```bash
# Create markdown file with all skill info
{
echo "# Personal Skills Inventory"
echo ""
for skill in ~/.claude/skills/*/SKILL.md; do
echo "## $(grep "name:" $skill | cut -d':' -f2-)"
echo ""
echo "**Description**: $(grep "description:" $skill | cut -d':' -f2-)"
echo ""
echo "**Location**: $skill"
echo ""
echo "---"
echo ""
done
} > ~/skills-inventory.md
```
### Generate Skills Summary
```bash
# Count skills by location
personal_count=$(ls ~/.claude/skills/ 2>/dev/null | wc -l)
project_count=$(ls .claude/skills/ 2>/dev/null | wc -l)
echo "Skills Summary:"
echo " Personal: $personal_count"
echo " Project: $project_count"
echo " Total: $((personal_count + project_count))"
```
## Troubleshooting
### Skill Not Appearing
**Check if file exists**:
```bash
ls ~/.claude/skills/my-skill/SKILL.md
```
**Check YAML syntax**:
```bash
head -n 10 ~/.claude/skills/my-skill/SKILL.md
```
**Verify location**:
- Personal: `~/.claude/skills/skill-name/SKILL.md`
- Project: `.claude/skills/skill-name/SKILL.md`
### Cannot Read Skill File
**Check permissions**:
```bash
ls -la ~/.claude/skills/my-skill/SKILL.md
# Fix if needed
chmod 644 ~/.claude/skills/my-skill/SKILL.md
```
### Skill Directory Empty
```bash
# Check if skills directory exists
ls -la ~/.claude/skills/
# Create if missing
mkdir -p ~/.claude/skills/
```
## Best Practices
### Regular Skill Audits
Periodically review your skills:
```bash
# List all skills with last modified date
ls -lt ~/.claude/skills/*/SKILL.md
# Find skills not modified in 90 days
find ~/.claude/skills/ -name "SKILL.md" -mtime +90
```
Consider updating or removing stale skills.
### Document Your Skills
Maintain a skills inventory:
```markdown
# My Claude Code Skills
## Active Skills
- **pdf-processing**: Extract and manipulate PDFs
- **data-analysis**: Analyze CSV and Excel files
- **commit-helper**: Generate git commit messages
## Experimental
- **new-skill**: Testing new approach
## Deprecated
- **old-skill**: Replaced by new-skill
```
### Track Skill Usage
Note which skills you use frequently:
```markdown
# Skill Usage Notes
## Frequently Used
- commit-helper (daily)
- pdf-processing (weekly)
## Rarely Used
- legacy-api (consider removing)
## Never Used
- experiment-1 (delete)
```

545
skills/managing-skills/updating.md Normal file
View File

@@ -0,0 +1,545 @@
# Updating Skills
Guidance for modifying and maintaining existing Agent Skills in Claude Code.
## Quick Update Process
### 1. Locate the Skill
```bash
# Personal skills
ls ~/.claude/skills/*/SKILL.md
# Project skills
ls .claude/skills/*/SKILL.md
# Find specific skill
find ~/.claude/skills -name "SKILL.md" -path "*/my-skill/*"
```
### 2. Edit SKILL.md
```bash
# Personal
code ~/.claude/skills/my-skill/SKILL.md
# Project
code .claude/skills/my-skill/SKILL.md
```
### 3. Apply Changes
Changes take effect the next time Claude Code starts.
**If Claude Code is already running**: Restart it to load updates.
## Common Update Scenarios
### Update Description
The description is critical for skill discovery. Update it when:
- Skill's purpose has expanded
- Trigger terms need refinement
- Usage context has changed
**Requirements**:
- Write in third person
- Include what the skill does AND when to use it
- Add specific trigger terms
- Maximum 1024 characters
**Before**:
```yaml
description: Helps with PDFs
```
**After**:
```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.
```
### Update Instructions
When adding new features or improving clarity:
**Before** (vague):
```markdown
## Instructions
Process the data and generate output.
```
**After** (specific):
```markdown
## Instructions
1. Load data from CSV file using pandas:
```python
import pandas as pd
df = pd.read_csv('data.csv')
```
2. Clean data:
- Remove null values
- Normalize formats
- Validate ranges
3. Generate summary statistics:
```python
summary = df.describe()
```
4. Export results to Excel:
```python
summary.to_excel('output.xlsx')
```
```
### Add Examples
Examples improve skill effectiveness. Add input/output pairs:
````markdown
## Examples
**Example 1: Simple Extraction**
Input: PDF with plain text
Output:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
for page in pdf.pages:
text = page.extract_text()
print(text)
```
**Example 2: Table Extraction**
Input: PDF with tables
Output:
```python
import pdfplumber
with pdfplumber.open("tables.pdf") as pdf:
for page in pdf.pages:
tables = page.extract_tables()
for table in tables:
# Process table data
pass
```
````
### Add or Update allowed-tools
Restrict which tools Claude can use when the skill is active:
**Before** (no restrictions):
```yaml
---
name: Data Analyzer
description: Analyze data files and generate reports
---
```
**After** (read-only):
```yaml
---
name: Data Analyzer
description: Analyze data files and generate reports
allowed-tools: Read, Grep, Glob
---
```
This ensures Claude can't modify files when using this skill.
### Split Large Skills
If SKILL.md exceeds 500 lines, use progressive disclosure:
**Before** (single large file):
```markdown
# PDF Processing
## Basic Text Extraction
[100 lines of content...]
## Advanced Table Extraction
[150 lines of content...]
## Form Filling
[200 lines of content...]
## API Reference
[300 lines of content...]
```
**After** (split into multiple files):
```
pdf-processing/
├── SKILL.md # Overview and quick start
├── tables.md # Table extraction guide
├── forms.md # Form filling guide
└── reference.md # Complete API docs
```
**SKILL.md**:
```markdown
# PDF Processing
## Quick Start
[Brief overview]
## Text Extraction
[Common usage]
## Advanced Features
- **Table Extraction**: See [tables.md](tables.md)
- **Form Filling**: See [forms.md](forms.md)
- **Complete API**: See [reference.md](reference.md)
```
### Update Reference Files
When updating longer reference files (>100 lines), include a table of contents:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and Setup
...
## Core Methods
...
```
## Refactoring Patterns
### Make Skills More Concise
Remove unnecessary explanations:
**Before** (too verbose):
```markdown
JSON (JavaScript Object Notation) is a data format that is commonly used
for APIs and configuration files. It uses key-value pairs and is human-readable.
To parse JSON in Python, you'll need to import the json module, which is
part of the standard library so you don't need to install anything extra.
```
**After** (concise):
```markdown
Parse JSON:
```python
import json
with open('data.json') as f:
data = json.load(f)
```
```
### Improve Terminology Consistency
**Before** (inconsistent):
```markdown
Use the API endpoint to send a request to the URL. The route will return...
The path can be accessed via the API...
```
**After** (consistent):
```markdown
Use the API endpoint to send a request. The endpoint will return...
The endpoint can be accessed via...
```
(Always use "API endpoint", never mix with "URL", "route", "path")
### Add Workflows for Complex Tasks
When users struggle with multi-step processes:
````markdown
## Data Analysis Workflow
Copy this checklist and track your progress:
```
Task Progress:
- [ ] Step 1: Load and validate data
- [ ] Step 2: Clean and normalize data
- [ ] Step 3: Perform analysis
- [ ] Step 4: Generate visualizations
- [ ] Step 5: Export results
```
**Step 1: Load and validate data**
```python
import pandas as pd
df = pd.read_csv('data.csv')
assert len(df) > 0, "Data file is empty"
assert not df.isnull().all().any(), "Column has all null values"
```
**Step 2: Clean and normalize data**
[Detailed instructions...]
**Step 3: Perform analysis**
[Detailed instructions...]
**Step 4: Generate visualizations**
[Detailed instructions...]
**Step 5: Export results**
[Detailed instructions...]
````
### Add Feedback Loops
For error-prone operations:
**Before** (no validation):
```markdown
1. Make changes to config.json
2. Deploy application
3. Test in production
```
**After** (with validation loop):
```markdown
1. Make changes to config.json
2. **Validate immediately**: `python scripts/validate_config.py`
3. If validation fails:
- Review error messages
- Fix issues in config.json
- Run validation again
4. **Only proceed when validation passes**
5. Deploy to staging
6. Test in staging environment
7. Deploy to production
```
## Version Management
### Document Changes
Add a version history section to track updates:
```markdown
# My Skill
## Version History
- v2.1.0 (2025-10-16): Added batch processing support
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added table extraction
- v1.0.0 (2025-09-01): Initial release
## Instructions
...
```
### Deprecate Features
When removing old approaches:
```markdown
## Current Method
Use the v2 API for all new integrations:
```python
from api.v2 import Client
client = Client(api_key="...")
```
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used a different client:
```python
from api.v1 import OldClient # Don't use
```
This API is no longer supported. Migrate to v2.
</details>
```
## Testing Updates
### 1. Verify YAML Syntax
After updating frontmatter:
```bash
cat SKILL.md | head -n 10
```
Check:
- Opening `---` on line 1
- Closing `---` before markdown content
- Valid YAML (no tabs, correct indentation)
- No special characters in unquoted strings
### 2. Test Description Changes
If you updated the description, test that Claude uses the skill appropriately:
Ask questions that match your new description and verify Claude activates the skill.
### 3. Check File References
If you added or renamed reference files, verify links work:
```bash
cd ~/.claude/skills/my-skill
# Check that referenced files exist
ls -l *.md
```
### 4. Verify Examples Run
If you added code examples, test them:
```bash
# Extract and run Python examples
python test_examples.py
```
## Common Update Mistakes
### ❌ Forgetting to Restart
**Problem**: Updates don't appear after editing SKILL.md
**Solution**: Restart Claude Code to load changes
### ❌ Breaking YAML Frontmatter
**Problem**: Skill stops working after update
**Check**:
```bash
cat SKILL.md | head -n 10
```
**Common issues**:
- Missing closing `---`
- Tabs instead of spaces
- Unquoted strings with colons
- Incorrect indentation
### ❌ Making Description Too Generic
**Problem**: Skill activates too often or not at all
**Before**:
```yaml
description: Helps with files
```
**After**:
```yaml
description: Analyzes log files and system metrics for performance monitoring, debugging, and diagnostics. Use when analyzing logs, system performance, or troubleshooting issues.
```
### ❌ Adding Too Much Content
**Problem**: SKILL.md becomes >500 lines
**Solution**: Use progressive disclosure:
- Keep core instructions in SKILL.md
- Move detailed content to separate reference files
- Link to reference files from SKILL.md
### ❌ Nested References
**Problem**: Claude doesn't find information in deeply nested files
**Bad** (too deep):
```markdown
# SKILL.md → references advanced.md
# advanced.md → references details.md
# details.md → has the actual info
```
**Good** (one level):
```markdown
# SKILL.md → directly references all docs
- advanced.md
- details.md
- examples.md
```
## Rollback Strategy
### Create Backup Before Major Changes
```bash
# Backup entire skill
cp -r ~/.claude/skills/my-skill ~/.claude/skills/my-skill.backup
# Or just backup SKILL.md
cp ~/.claude/skills/my-skill/SKILL.md ~/.claude/skills/my-skill/SKILL.md.backup
```
### Restore from Backup
```bash
# Restore entire skill
rm -rf ~/.claude/skills/my-skill
mv ~/.claude/skills/my-skill.backup ~/.claude/skills/my-skill
# Or just restore SKILL.md
mv ~/.claude/skills/my-skill/SKILL.md.backup ~/.claude/skills/my-skill/SKILL.md
```
### Use Version Control
For project skills (in git repositories):
```bash
# See what changed
git diff .claude/skills/my-skill/SKILL.md
# Revert changes
git checkout .claude/skills/my-skill/SKILL.md
# Commit updates
git add .claude/skills/my-skill/
git commit -m "Update my-skill: add batch processing support"
```
## Team Collaboration
### Communicate Changes
For project skills, notify team members:
```bash
git commit -m "Update PDF skill: add form filling capability
- Added form filling workflow
- Updated description to include 'forms' trigger
- Added forms.md reference guide
Team members should restart Claude Code to get updates."
git push
```
### Review Process
For shared skills, consider a review process:
1. Create feature branch
2. Update skill
3. Test thoroughly
4. Create pull request
5. Have teammate review
6. Merge when approved
7. Team members pull and restart