agentsys 5.0.0

package/adapters/opencode/skills/enhance-skills/SKILL.md

@@ -0,0 +1,443 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+name: enhance-skills
+description: "Use when reviewing SKILL.md files for structure and trigger quality."
+version: 5.0.0
+argument-hint: "[path] [--fix]"
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# enhance-skills
+
+Analyze skill definitions for trigger quality, structure, and discoverability.
+
+## Workflow
+
+1. **Discover** - Find all SKILL.md files
+2. **Parse** - Extract frontmatter and content
+3. **Check** - Run all pattern checks against knowledge below
+4. **Filter** - Apply certainty filtering
+5. **Report** - Generate markdown output
+6. **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: `~/.opencode/skills/<name>/SKILL.md`
+- Project: `.opencode/skills/<name>/SKILL.md`
+
+### Invocation Control Patterns
+
+**Manual Only (for skills with side effects):**
+```yaml
+---
+name: deploy
+description: Deploy to production
+disable-model-invocation: true
+---
+```
+
+**Background Knowledge (auto-only, hidden from menu):**
+```yaml
+---
+name: legacy-context
+description: How the legacy payment system works
+user-invocable: false
+---
+```
+
+**Full Access (default - both auto and manual):**
+```yaml
+---
+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:
+
+```yaml
+---
+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 `/context` command
+- Increase via: `SLASH_COMMAND_TOOL_CHAR_BUDGET=30000`
+
+### Subagent Execution
+
+When using `context: fork`:
+
+```yaml
+---
+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
+
+```yaml
+---
+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
+- `name` field (lowercase, max 64 chars)
+- `description` field (max 1024 chars)
+
+**Recommended:**
+- `version` field for tracking
+- `argument-hint` for skills accepting input
+- `allowed-tools` for security
+- `model` when 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-invocation` not set
+- Dangerous auto-invocable skills (can accidentally trigger)
+
+### 4. Tool Restrictions (HIGH Certainty)
+
+**Check:** Tools are appropriately scoped
+
+**Flag:**
+- Unrestricted `Bash` (should be `Bash(git:*)` or similar)
+- Read-only skills with Write/Edit
+- Research skills with Task tool
+
+### 5. Content Scope (MEDIUM Certainty)
+
+**Guidelines:**
+- SKILL.md under 500 lines
+- Large content in `references/` subdirectory
+- Max 3 dynamic injections
+
+**Flag:**
+- SKILL.md over 500 lines
+- More than 3 `!`backtick`` injections
+- Embedded large examples (move to examples.md)
+
+### 6. Structure Quality (MEDIUM Certainty)
+
+**Recommended Sections:**
+- Purpose/overview
+- Required checks or workflow steps
+- Output format
+- Examples (if complex)
+
+### 7. Context Configuration (MEDIUM Certainty)
+
+**Check:** Context settings are appropriate
+
+**Flag:**
+- `context: fork` without `agent` type
+- `agent` type without `context: fork`
+- Mismatch between agent type and allowed-tools
+
+### 8. Anti-Patterns (LOW Certainty)
+
+- Vague descriptions without specific triggers
+- Too many responsibilities (should split into multiple skills)
+- Missing `argument-hint` for skills that clearly need input
+- Redundant chain-of-thought instructions (modern models don't need "think step by step")
+
+---
+
+## Auto-Fix Implementations
+
+### 1. Missing frontmatter
+```yaml
+---
+name: skill-name
+description: "Use when..."
+version: 4.2.0
+---
+```
+
+### 2. Missing trigger phrase
+Add "Use when user asks..." prefix to description
+
+### 3. Unrestricted Bash
+Replace `Bash` with `Bash(git:*)` or appropriate scope
+
+---
+
+## Output Format
+
+```markdown
+## Skill Analysis: {skill-name}
+
+**File**: {path}
+
+### Summary
+- HIGH: {count} issues
+- MEDIUM: {count} issues
+
+### Frontmatter Issues ({n})
+| Issue | Fix | Certainty |
+
+### Trigger Issues ({n})
+| Issue | Fix | Certainty |
+
+### Invocation Issues ({n})
+| Issue | Fix | Certainty |
+
+### Tool Issues ({n})
+| Issue | Fix | Certainty |
+
+### Scope Issues ({n})
+| Issue | Fix | Certainty |
+```
+
+---
+
+## Pattern Statistics
+
+| Category | Patterns | Auto-Fixable |
+|----------|----------|--------------|
+| Frontmatter | 5 | 2 |
+| Trigger | 2 | 1 |
+| Invocation | 3 | 1 |
+| Tool | 3 | 1 |
+| Scope | 3 | 0 |
+| Structure | 2 | 0 |
+| Context | 3 | 0 |
+| Anti-Pattern | 4 | 0 |
+| **Total** | **25** | **5** |
+
+---
+
+<examples>
+### Example: Missing Trigger Phrase
+
+<bad_example>
+```yaml
+name: code-review
+description: "Reviews code for issues"
+```
+**Why it's bad**: No trigger context for auto-discovery.
+</bad_example>
+
+<good_example>
+```yaml
+name: code-review
+description: "Use when user asks to 'review code', 'check this PR'. Reviews code for issues."
+```
+**Why it's good**: Clear trigger phrases enable auto-discovery.
+</good_example>
+
+### Example: Dangerous Auto-Invocation
+
+<bad_example>
+```yaml
+name: deploy
+description: "Deploys code to production"
+```
+**Why it's bad**: Side-effect skill could be auto-invoked accidentally.
+</bad_example>
+
+<good_example>
+```yaml
+name: deploy
+description: "Deploy to production environment"
+disable-model-invocation: true
+```
+**Why it's good**: Manual-only prevents accidental deployments.
+</good_example>
+
+### Example: Unrestricted Tools
+
+<bad_example>
+```yaml
+name: git-helper
+allowed-tools: Bash
+```
+**Why it's bad**: Unrestricted Bash allows any command.
+</bad_example>
+
+<good_example>
+```yaml
+name: git-helper
+allowed-tools: Bash(git:*)
+```
+**Why it's good**: Scoped to only git commands.
+</good_example>
+
+### Example: Oversized Skill
+
+<bad_example>
+```markdown
+# Complex Analysis
+[800 lines of detailed instructions]
+```
+**Why it's bad**: Large skills consume context budget (15K char limit).
+</bad_example>
+
+<good_example>
+```markdown
+# Complex Analysis
+Core instructions here (under 500 lines).
+For details, see `references/detailed-guide.md`.
+```
+**Why it's good**: Core skill is concise; details in separate files.
+</good_example>
+
+### Example: Context/Agent Mismatch
+
+<bad_example>
+```yaml
+name: researcher
+context: fork
+# Missing agent type
+```
+**Why it's bad**: Fork context without specifying agent type.
+</bad_example>
+
+<good_example>
+```yaml
+name: researcher
+context: fork
+agent: Explore
+allowed-tools: Read, Grep, Glob
+```
+**Why it's good**: Agent type matches allowed tools (Explore = read-only).
+</good_example>
+</examples>
+
+---
+
+## Constraints
+
+- Only apply auto-fixes for HIGH certainty issues
+- Consider skill context when evaluating trigger quality
+- Never remove content, only suggest improvements
+- Validate against embedded knowledge reference above