enhance-skills
Use when reviewing SKILL.md files for structure and trigger quality.
agent-sh · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agent-sh/agentsys --skill enhance-skills技能说明
name: enhance-skills description: "Use when reviewing SKILL.md files for structure and trigger quality." version: 5.1.0 argument-hint: "[path] [--fix]"
enhance-skills
Analyze skill definitions for trigger quality, structure, and discoverability.
Workflow
- Discover - Find all SKILL.md files
- Parse - Extract frontmatter and content
- Check - Run all pattern checks against knowledge below
- Filter - Apply certainty filtering
- Report - Generate markdown output
- Fix - Apply auto-fixes if --fix flag present
Skill Knowledge Reference
Frontmatter Fields (Complete Reference)
| Field | Required | Description | Validation |
|---|---|---|---|
name | No | Display name, defaults to directory name | lowercase, max 64 chars |
description | Recommended | What skill does and when to use | max 1024 chars, should include trigger |
argument-hint | No | Autocomplete hint, e.g., [file-path] | keep under 30 chars |
disable-model-invocation | No | true = manual only (for side effects) | boolean, default false |
user-invocable | No | false = hidden from / menu (auto-only) | boolean, default true |
allowed-tools | No | Tools Claude can use without permission | comma-separated list |
model | No | Specific model when skill is active | opus, sonnet, haiku |
context | No | fork = run in isolated subagent context | fork or omit |
agent | No | Subagent type for execution | Explore, Plan, general-purpose |
hooks | No | Skill-scoped lifecycle hooks | PreToolUse, PostToolUse |
Directory Structure
skills/my-skill/
├── SKILL.md # Required - core definition (under 500 lines)
├── reference.md # Optional - detailed documentation
├── examples.md # Optional - usage examples
└── scripts/ # Optional - helper scripts
└── helper.py
Storage Locations:
- Enterprise: Managed settings
- Personal:
~/.claude/skills/<name>/SKILL.md - Project:
.claude/skills/<name>/SKILL.md
Invocation Control Patterns
Manual Only (for skills with side effects):
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---
Background Knowledge (auto-only, hidden from menu):
---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---
Full Access (default - both auto and manual):
---
name: review
description: Use when user asks to review code. Checks quality and security.
---
Trigger Phrases
Description should include trigger context for auto-discovery:
- "Use when user asks..."
- "Use when..."
- "Invoke when..."
Good: "Use when user asks to 'review code', 'check PR', or 'code review'"
Bad: "Reviews code" (no trigger context)
Dynamic Context Injection
Skills can inject dynamic content using backtick syntax:
---
name: pr-summary
description: Summarize PR changes
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
Rules:
- Use
!followed by backtick-wrapped command - Limit to 3 injections per skill
- Each injection adds to context budget
String Substitutions
| Variable | Description |
|---|---|
$ARGUMENTS | All arguments passed when invoking |
${CLAUDE_SESSION_ID} | Current session ID |
Context Budget
- Skill descriptions have ~15,000 character default limit
- Content beyond limit is truncated
- Check with
/contextcommand - Increase via:
SLASH_COMMAND_TOOL_CHAR_BUDGET=30000
Subagent Execution
When using context: fork:
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---
Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings
Agent Types:
| Agent | Purpose | Tool Access |
|---|---|---|
Explore | Read-only codebase exploration | Read, Grep, Glob only |
Plan | Planning-focused reasoning | Read, analysis tools |
general-purpose | Full capabilities | All tools |
Skill-Scoped Hooks
---
name: secure-operations
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---
Tool Restrictions
Use scoped tool patterns for security:
| Pattern | Meaning |
|---|---|
Bash(git:*) | Only git commands |
Bash(npm:*) | Only npm commands |
Bash(gh:*) | Only GitHub CLI |
Read(src/**) | Only files in src/ |
Detection Patterns
1. Frontmatter Validation (HIGH Certainty)
Required:
- YAML frontmatter with
---delimiters namefield (lowercase, max 64 chars)descriptionfield (max 1024 chars)
Recommended:
versionfield for trackingargument-hintfor skills accepting inputallowed-toolsfor securitymodelwhen specific model required
Flag:
- Missing frontmatter delimiters
- Invalid field values (uppercase name, description >1024 chars)
2. Trigger Quality (HIGH Certainty)
Check: Description includes trigger phrase Trigger patterns: "Use when", "Invoke when", "Use when user asks"
Flag:
- Description without trigger context
- Vague descriptions like "Useful tool" or "Does stuff"
3. Invocation Control (HIGH Certainty)
Check: Side-effect skills are protected
Flag:
- Skills with deploy/ship/publish in name but
disable-model-invocationnot set - Dangerous auto-invocable skills (can accidentally trigger)
4. Tool Restrictions (HIGH Certainty)
Check: Tools are appropriately scoped
Flag:
- Unrestricted
Bash(should beBash(git:*)or similar) - Read-only skills with Write/Edit
- Research skills with Task tool
5. Content Scope (MEDIUM Certainty)
**Guideli
阅读完整来源 ↗