@waoooo/claude-skills 1.0.0

package/skills/creating-skills/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: creating-skills
+description: Guide for creating Claude Code skills following Anthropic's official best practices. Use when user wants to create a new skill, build a skill, write SKILL.md, update an existing skill, or needs skill creation guidelines. Provides structure, frontmatter fields, naming conventions, and new features like dynamic context injection and subagent execution.
+---
+
+# Creating skills
+
+Guide for creating Claude Code skills following Anthropic's official best practices.
+
+## Quick start
+
+```bash
+# 1. Create skill directory
+mkdir -p ~/.claude/skills/<skill-name>
+
+# 2. Create SKILL.md with frontmatter
+cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
+---
+name: <skill-name>
+description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
+---
+
+# <Skill title>
+
+<Instructions for the skill workflow>
+EOF
+
+# 3. Add optional resources as needed
+mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}
+```
+
+## SKILL.md structure
+
+### Frontmatter (YAML between `---` markers)
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Display name. Defaults to directory name. Lowercase, hyphens, max 64 chars. |
+| `description` | Recommended | What + when + capabilities. Max 1024 chars. Determines when Claude activates the skill. |
+| `allowed-tools` | No | Tools Claude can use without asking permission when skill is active. |
+| `argument-hint` | No | Autocomplete hint for arguments. Example: `[issue-number]` |
+| `disable-model-invocation` | No | `true` to prevent auto-invocation (manual `/name` only). |
+| `user-invocable` | No | `false` to hide from `/` menu (background knowledge only). |
+| `model` | No | Model override when skill is active. |
+| `context` | No | `fork` to run in isolated subagent context. |
+| `agent` | No | Subagent type when `context: fork`. Built-in: `Explore`, `Plan`, `general-purpose`. |
+| `hooks` | No | Lifecycle hooks scoped to this skill. |
+
+### Invocation control matrix
+
+| Configuration | User can invoke | Claude can invoke |
+|---------------|-----------------|-------------------|
+| (defaults) | Yes | Yes |
+| `disable-model-invocation: true` | Yes | No |
+| `user-invocable: false` | No | Yes |
+
+### Description formula
+
+```
+<What it does>. Use when <trigger phrases>. <Key capabilities>.
+```
+
+Include action verbs ("create", "handle"), user intent ("wants to", "needs to"), and domain keywords users would say.
+
+## Directory structure
+
+```
+skill-name/
+├── SKILL.md              # Required: instructions (keep under 500 lines)
+├── scripts/              # Optional: executable code (deterministic, token-efficient)
+├── references/           # Optional: docs loaded into context on demand
+└── assets/               # Optional: files used in output, NOT loaded into context
+                          #   (templates, images, fonts, boilerplate)
+```
+
+### Progressive disclosure (3-level loading)
+
+1. **Metadata** (name + description) - always in context (~100 tokens per skill)
+2. **SKILL.md body** - loaded when skill triggers (keep under 5k words)
+3. **Bundled resources** - loaded as needed by Claude
+
+Reference supporting files from SKILL.md so Claude knows they exist. Keep references one level deep. For files over 100 lines, include a table of contents.
+
+### Scripts vs references vs assets
+
+| Type | Purpose | Loaded into context? |
+|------|---------|---------------------|
+| `scripts/` | Deterministic operations, complex processing | No (executed via bash) |
+| `references/` | Documentation Claude reads while working | Yes, on demand |
+| `assets/` | Templates, images, fonts for output | No (copied/used in output) |
+
+Only create scripts when they add value: complex multi-step processing, repeated code generation, deterministic reliability. Not for single-command wrappers.
+
+## Dynamic features
+
+### Context injection
+
+Inject shell command output into skill content before loading:
+
+```markdown
+## Recent commits
+!`git log --oneline -5 2>/dev/null`
+```
+
+The output replaces the directive when the skill loads.
+
+### String substitutions
+
+Pass arguments to skills invoked via `/skill-name arg1 arg2`:
+
+| Variable | Value |
+|----------|-------|
+| `$ARGUMENTS` | Full argument string |
+| `$ARGUMENTS[0]`, `$ARGUMENTS[1]` | Individual arguments |
+| `$1`, `$2` | Shorthand for `$ARGUMENTS[N]` |
+
+### Subagent execution
+
+Run a skill in isolated context with `context: fork`:
+
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly.
+context: fork
+agent: Explore
+---
+```
+
+## Degrees of freedom
+
+Match specificity to the task's fragility:
+
+| Level | When to use | Example |
+|-------|-------------|---------|
+| **High** (text instructions) | Multiple valid approaches, context-dependent | "Analyze the code and suggest improvements" |
+| **Medium** (pseudocode/scripts with params) | Preferred pattern exists, some variation OK | Script with configurable parameters |
+| **Low** (specific scripts, few params) | Fragile operations, consistency critical | Exact sequence of API calls |
+
+## Naming conventions
+
+- Lowercase, hyphens between words, max 64 chars
+- Styles: gerund (`processing-pdfs`), noun phrase (`github-pr-creation`), prefixed group (`github-pr-*`)
+
+## Important rules
+
+- **ALWAYS** write descriptions that include WHAT + WHEN triggers + capabilities
+- **ALWAYS** keep SKILL.md under 500 lines, split to references when approaching
+- **ALWAYS** reference bundled files from SKILL.md so Claude discovers them
+- **NEVER** duplicate info between SKILL.md and reference files
+- **NEVER** create wrapper scripts for single commands
+- **NEVER** include extraneous files (README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md)
+- **NEVER** explain things Claude already knows (standard libraries, common tools, basic patterns)
+
+## References
+
+- `references/official_best_practices.md` - Principles, anti-patterns, quality checklist, testing
+- `references/skill_examples.md` - Concrete skill examples with new features

package/skills/creating-skills/references/official_best_practices.md

@@ -0,0 +1,128 @@
+# Official best practices for skills
+
+Source: [Claude Code skills docs](https://code.claude.com/docs/en/skills), [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), [Anthropic skills repo](https://github.com/anthropics/skills)
+
+---
+
+## Core principle: Claude is already smart
+
+> "Default assumption: Claude is already very smart. Only add context Claude doesn't already have."
+
+**Challenge each piece of information:**
+- Does Claude really need this explanation?
+- Can I assume Claude knows this?
+- Does this paragraph justify its token cost?
+
+**What NOT to include**: basic programming concepts, common tool usage (git, npm), standard library docs, well-known patterns.
+
+**What TO include**: project-specific conventions, custom workflows, non-obvious requirements, domain knowledge Claude wouldn't have.
+
+## Progressive disclosure
+
+Skills use a three-level loading system:
+
+1. **Metadata** (name + description) - always in context (~100 words per skill)
+2. **SKILL.md body** - when skill triggers (<5k words recommended)
+3. **Bundled resources** - as needed (scripts execute without loading; references load on demand)
+
+### Context budget
+
+Skill descriptions share a budget that scales at 2% of the context window, with a fallback of 16,000 characters. Override with `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var.
+
+### Splitting patterns
+
+When SKILL.md approaches 500 lines, split content into separate files:
+
+- **Pattern 1: High-level guide with references** - Keep workflow in SKILL.md, move detailed docs to references/
+- **Pattern 2: Domain-specific organization** - One reference per domain area (e.g., `references/api_docs.md`, `references/schemas.md`)
+- **Pattern 3: Conditional details** - Keep decision logic in SKILL.md, move variant-specific details to references/
+
+**Guidelines:**
+- Avoid deeply nested references - keep one level deep from SKILL.md
+- For files over 100 lines, include a table of contents at the top
+- For very large references (>10k words), include grep search patterns in SKILL.md
+- Information should live in either SKILL.md OR references, not both
+
+## Frontmatter validation rules
+
+| Field | Constraint |
+|-------|-----------|
+| `name` | Max 64 chars, lowercase + numbers + hyphens only, no XML tags, no reserved words ("anthropic", "claude") |
+| `description` | Max 1024 chars, non-empty if provided, no XML tags |
+| Allowed properties | `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`, `argument-hint`, `disable-model-invocation`, `user-invocable`, `model`, `context`, `agent`, `hooks` |
+
+## Skills and commands unification
+
+Custom slash commands (`.claude/commands/*.md`) and skills (`.claude/skills/*/SKILL.md`) are now unified. Both create `/name` invocations and support the same frontmatter. Existing commands files continue to work. If a skill and a command share the same name, the skill takes precedence.
+
+## Discovery hierarchy
+
+Skills are discovered from multiple locations (higher priority wins):
+
+1. **Enterprise** (managed settings)
+2. **Personal** (`~/.claude/skills/`)
+3. **Project** (`.claude/skills/`)
+4. **Plugin** (namespaced as `plugin-name:skill-name`)
+
+Additional directories via `--add-dir` are also supported with live change detection.
+
+## User confirmation patterns
+
+**ALWAYS confirm before:**
+- Modifying user files
+- Running destructive commands
+- Creating external resources (PRs, issues, deployments)
+- Irreversible operations
+
+**Don't over-confirm:**
+- Read-only operations
+- Reversible actions
+- Intermediate steps in an approved workflow
+
+## Anti-patterns
+
+| Pattern | Problem | Instead |
+|---------|---------|---------|
+| Wrapper scripts | No value added | Inline commands |
+| Verbose explanations | Token waste | Trust Claude's knowledge |
+| Multiple paths | Confusing | One clear workflow |
+| Custom systems | Non-standard | Use official patterns |
+| Over-confirmation | Friction | Confirm only critical actions |
+| Deeply nested references | Hard to discover | Keep one level deep |
+| Duplicated info | Drift risk, token waste | Single source of truth |
+| Extraneous files | Clutter | Only SKILL.md + resources |
+
+## Quality checklist
+
+Before finalizing a skill:
+
+- [ ] **Frontmatter**: description present, clear, under 1024 chars
+- [ ] **Description**: includes WHAT + WHEN triggers + capabilities
+- [ ] **Naming**: lowercase, hyphens, max 64 chars
+- [ ] **Body**: under 500 lines, no duplication with references
+- [ ] **Resources**: referenced from SKILL.md, one level deep
+- [ ] **Scripts**: only value-add, not wrappers
+- [ ] **Rules**: critical constraints marked with **ALWAYS**/**NEVER**
+- [ ] **Test**: skill triggers on expected phrases
+
+## Testing
+
+### Trigger testing
+Verify skill activates on expected user phrases. Test with multiple phrasings.
+
+### Model testing
+Test with all models you plan to support (Haiku, Sonnet, Opus have different capabilities). Build evaluations before writing extensive documentation.
+
+### Edge cases
+- Missing prerequisites
+- Invalid input
+- Partial completion
+
+## What NOT to include in a skill
+
+A skill should only contain files that directly support its functionality:
+
+- No README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md
+- No user-facing documentation (the skill IS the documentation for Claude)
+- No setup/testing procedures
+- No auxiliary context about the creation process

package/skills/creating-skills/references/skill_examples.md

@@ -0,0 +1,199 @@
+# Skill examples
+
+Concrete examples demonstrating skill patterns and new features.
+
+---
+
+## Example 1: minimal skill
+
+The simplest possible skill:
+
+```yaml
+---
+description: Formats code following project conventions. Use when user wants to format, lint, or clean up code.
+---
+```
+
+```markdown
+# Code formatter
+
+Run the project formatter on changed files.
+
+## Workflow
+
+1. Detect project type and formatter
+2. Run formatter on staged/changed files
+3. Report results
+
+## Important rules
+
+- **ALWAYS** check for project-specific formatter config before using defaults
+- **NEVER** format files outside the current change set
+```
+
+Note: `name` is omitted (defaults to directory name). Only `description` is provided.
+
+---
+
+## Example 2: dynamic context injection
+
+A skill that adapts to the current project:
+
+```yaml
+---
+name: git-commit
+description: Creates commits following project conventions. Use when user wants to commit changes.
+---
+```
+
+```markdown
+# Git commit
+
+## Recent project commits
+!`git log --oneline -5 2>/dev/null`
+
+## Current branch
+!`git rev-parse --abbrev-ref HEAD 2>/dev/null`
+
+Match the style of recent commits above when creating new ones.
+```
+
+The `!`command`` directives run at load time and inject their output, so Claude sees actual commit history instead of placeholder text.
+
+---
+
+## Example 3: invocation control
+
+### Manual-only skill (no auto-invocation)
+
+```yaml
+---
+name: deploy
+description: Deploy the application to production.
+disable-model-invocation: true
+argument-hint: [environment]
+---
+```
+
+Claude will never auto-invoke this skill. Users must type `/deploy staging` explicitly.
+
+### Background knowledge (no user invocation)
+
+```yaml
+---
+name: project-conventions
+description: Project coding conventions and architectural decisions.
+user-invocable: false
+---
+```
+
+Claude auto-loads this as context when relevant, but it doesn't appear in the `/` menu.
+
+---
+
+## Example 4: subagent execution
+
+A skill that runs in isolated context:
+
+```yaml
+---
+name: codebase-analysis
+description: Analyze codebase architecture and patterns. Use when user wants to understand code structure.
+context: fork
+agent: Explore
+---
+```
+
+```markdown
+# Codebase analysis
+
+Explore the codebase and report:
+1. Project structure and framework
+2. Key architectural patterns
+3. Entry points and data flow
+4. Test coverage approach
+
+Return a structured summary.
+```
+
+With `context: fork`, this runs in a separate subagent without consuming the main conversation's context.
+
+---
+
+## Example 5: skill with arguments
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue. Use when user wants to fix, resolve, or address an issue.
+argument-hint: [issue-number]
+---
+```
+
+```markdown
+# Fix issue
+
+## Issue details
+!`gh issue view $1 --json title,body,labels 2>/dev/null`
+
+Fix the issue described above. Follow project conventions.
+```
+
+`$1` is replaced with the first argument when the user types `/fix-issue 42`.
+
+---
+
+## Example 6: skill with allowed tools
+
+```yaml
+---
+name: database-migration
+description: Create and run database migrations. Use when user wants to migrate, create migration, or update schema.
+allowed-tools: ["Bash", "Read", "Write", "Edit"]
+---
+```
+
+Tools listed in `allowed-tools` won't prompt for permission when this skill is active.
+
+---
+
+## Description: good vs bad
+
+**Good** - concise, specific triggers, clear capabilities:
+```
+Handles PR review comments with severity classification. Use when user
+wants to resolve PR comments, handle review feedback, or fix review
+comments. Fetches via GitHub CLI, classifies by severity, proposes fixes.
+```
+
+**Bad** - verbose, filler words, redundant:
+```
+Comprehensive GitHub Pull Request management system for feature
+development workflow. Use this skill when the user wants to create, verify,
+or manage Pull Requests on GitHub repositories. This skill handles the
+complete workflow - validates task completion against project documentation,
+runs tests, generates PR title and description following Conventional Commits,
+suggests appropriate labels, and creates the PR using GitHub CLI.
+```
+
+Problems: "Comprehensive", "complete workflow" are filler. Redundant explanations. Too verbose for a description field.
+
+---
+
+## Resource organization examples
+
+### Scripts that add value
+
+| Script | Why it's justified |
+|--------|-------------------|
+| `scripts/classify_severity.py` | Complex multi-step classification with JSON output |
+| `scripts/analyze_commits.py` | Git log parsing + task file matching across multiple files |
+| `scripts/validate_skill.py` | Multi-field validation with structured error reporting |
+
+### Scripts to avoid
+
+| Script | Why it's bad | Instead |
+|--------|-------------|---------|
+| `scripts/fetch_comments.sh` | Wraps `gh api repos/.../comments` | Inline command |
+| `scripts/run_tests.sh` | Wraps `make test` | Inline command |
+| `scripts/get_branch.sh` | Wraps `git rev-parse --abbrev-ref HEAD` | Inline command |

package/skills/docx/LICENSE.txt

@@ -0,0 +1,30 @@
+© 2025 Anthropic, PBC. All rights reserved.
+
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+Anthropic regarding use of Anthropic's services. If no separate agreement
+exists, use is governed by Anthropic's Consumer Terms of Service or
+Commercial Terms of Service, as applicable:
+https://www.anthropic.com/legal/consumer-terms
+https://www.anthropic.com/legal/commercial-terms
+Your applicable agreement is referred to as the "Agreement." "Services" are
+as defined in the Agreement.
+
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+
+Anthropic retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.