Improve/skill review optimization

.github/workflows/skill-review.yml

@@ -0,0 +1,13 @@
+name: Skill Review
+on:
+  pull_request:
+    paths: ['**/SKILL.md']
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main

plugins/plugin-dev/skills/agent-development/SKILL.md

@@ -1,7 +1,6 @@
 ---
-name: Agent Development
-description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
-version: 0.1.0
+name: agent-development
+description: "Generates agent YAML frontmatter, writes system prompts, configures tool permissions, and sets triggering conditions for Claude Code plugin agents. Use when creating, editing, or reviewing agent files — covers name/description/model/color/tools fields, example blocks, system prompt structure, validation rules, and testing workflows."
 ---
 
 # Agent Development for Claude Code Plugins
@@ -116,28 +115,17 @@ assistant: "[How Claude should respond]"
 
 Which model the agent should use.
 
-**Options:**
-- `inherit` - Use same model as parent (recommended)
-- `sonnet` - Claude Sonnet (balanced)
-- `opus` - Claude Opus (most capable, expensive)
-- `haiku` - Claude Haiku (fast, cheap)
+**Options:** `inherit` (recommended), `sonnet`, `opus`, `haiku`
 
-**Recommendation:** Use `inherit` unless agent needs specific model capabilities.
+Use `inherit` unless the agent needs specific model capabilities.
 
 ### color (required)
 
 Visual identifier for agent in UI.
 
 **Options:** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
 
-**Guidelines:**
-- Choose distinct colors for different agents in same plugin
-- Use consistent colors for similar agent types
-- Blue/cyan: Analysis, review
-- Green: Success-oriented tasks
-- Yellow: Caution, validation
-- Red: Critical, security
-- Magenta: Creative, generation
+Choose distinct colors for different agents in the same plugin.
 
 ### tools (optional)
 
@@ -161,58 +149,7 @@ tools: ["Read", "Write", "Grep", "Bash"]
 
 ## System Prompt Design
 
-The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
-
-### Structure
-
-**Standard template:**
-```markdown
-You are [role] specializing in [domain].
-
-**Your Core Responsibilities:**
-1. [Primary responsibility]
-2. [Secondary responsibility]
-3. [Additional responsibilities...]
-
-**Analysis Process:**
-1. [Step one]
-2. [Step two]
-3. [Step three]
-[...]
-
-**Quality Standards:**
-- [Standard 1]
-- [Standard 2]
-
-**Output Format:**
-Provide results in this format:
-- [What to include]
-- [How to structure]
-
-**Edge Cases:**
-Handle these situations:
-- [Edge case 1]: [How to handle]
-- [Edge case 2]: [How to handle]
-```
-
-### Best Practices
-
-✅ **DO:**
-- Write in second person ("You are...", "You will...")
-- Be specific about responsibilities
-- Provide step-by-step process
-- Define output format
-- Include quality standards
-- Address edge cases
-- Keep under 10,000 characters
-
-❌ **DON'T:**
-- Write in first person ("I am...", "I will...")
-- Be vague or generic
-- Omit process steps
-- Leave output format undefined
-- Skip quality guidance
-- Ignore error cases
+The markdown body after frontmatter becomes the agent's system prompt. Write in second person ("You are..."). Include: role definition, core responsibilities, step-by-step process, output format, and edge case handling. Keep under 10,000 characters.
 
 ## Creating Agents
 
@@ -257,33 +194,6 @@ See `examples/agent-creation-prompt.md` for complete template.
 6. Write system prompt with structure above
 7. Save as `agents/agent-name.md`
 
-## Validation Rules
-
-### Identifier Validation
-
-```
-✅ Valid: code-reviewer, test-gen, api-analyzer-v2
-❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
-```
-
-**Rules:**
-- 3-50 characters
-- Lowercase letters, numbers, hyphens only
-- Must start and end with alphanumeric
-- No underscores, spaces, or special characters
-
-### Description Validation
-
-**Length:** 10-5,000 characters
-**Must include:** Triggering conditions and examples
-**Best:** 200-1,000 characters with 2-4 examples
-
-### System Prompt Validation
-
-**Length:** 20-10,000 characters
-**Best:** 500-3,000 characters
-**Structure:** Clear responsibilities, process, output format
-
 ## Agent Organization
 
 ### Plugin Agents Directory

plugins/plugin-dev/skills/plugin-structure/SKILL.md

@@ -1,7 +1,6 @@
 ---
-name: Plugin Structure
-description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.
-version: 0.1.0
+name: plugin-structure
+description: "Scaffold and organize Claude Code plugins with the correct directory layout, plugin.json manifest, component types (commands, agents, skills, hooks, MCP servers), portable path references, and auto-discovery conventions. Use when creating a plugin, setting up plugin.json, organizing plugin components, configuring auto-discovery, or using ${CLAUDE_PLUGIN_ROOT}."
 ---
 
 # Plugin Structure for Claude Code
@@ -55,11 +54,7 @@ The manifest defines plugin metadata and configuration. Located at `.claude-plug
 }
 ```
 
-**Name requirements:**
-- Use kebab-case format (lowercase with hyphens)
-- Must be unique across installed plugins
-- No spaces or special characters
-- Example: `code-review-assistant`, `test-runner`, `api-docs`
+**Name requirements:** kebab-case, unique across installed plugins (e.g. `code-review-assistant`, `test-runner`).
 
 ### Recommended Metadata
 
@@ -80,9 +75,6 @@ The manifest defines plugin metadata and configuration. Located at `.claude-plug
 }
 ```
 
-**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)
-**Keywords**: Use for plugin discovery and categorization
-
 ### Component Path Configuration
 
 Specify custom paths for components (supplements default directories):
@@ -97,13 +89,7 @@ Specify custom paths for components (supplements default directories):
 }
 ```
 
-**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
-
-**Path rules:**
-- Must be relative to plugin root
-- Must start with `./`
-- Cannot use absolute paths
-- Support arrays for multiple locations
+**Important**: Custom paths supplement defaults—they don't replace them. Paths must be relative (start with `./`) and support arrays for multiple locations.
 
 ## Component Organization
 
@@ -265,21 +251,13 @@ Use `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path refer
 }
 ```
 
-**Why it matters**: Plugins install in different locations depending on:
-- User installation method (marketplace, local, npm)
-- Operating system conventions
-- User preferences
-
 **Where to use it**:
 - Hook command paths
 - MCP server command arguments
 - Script execution references
 - Resource file paths
 
-**Never use**:
-- Hardcoded absolute paths (`/Users/name/plugins/...`)
-- Relative paths from working directory (`./scripts/...` in commands)
-- Home directory shortcuts (`~/plugins/...`)
+**Never use**: hardcoded absolute paths, relative paths from working directory, or home directory shortcuts (`~/`).
 
 ### Path Resolution Rules
 
@@ -319,87 +297,18 @@ source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
 - `database-migrations/`
 - `error-handling/`
 
-### Supporting Files
-
-**Scripts**: Use descriptive kebab-case names with appropriate extensions
-- `validate-input.sh`
-- `generate-report.py`
-- `process-data.js`
-
-**Documentation**: Use kebab-case markdown files
-- `api-reference.md`
-- `migration-guide.md`
-- `best-practices.md`
-
-**Configuration**: Use standard names
-- `hooks.json`
-- `.mcp.json`
-- `plugin.json`
+All supporting files (scripts, docs, config) should also use kebab-case naming.
 
 ## Auto-Discovery Mechanism
 
-Claude Code automatically discovers and loads components:
-
-1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables
-2. **Commands**: Scans `commands/` directory for `.md` files
-3. **Agents**: Scans `agents/` directory for `.md` files
-4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`
-5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest
-6. **MCP servers**: Loads configuration from `.mcp.json` or manifest
-
-**Discovery timing**:
-- Plugin installation: Components register with Claude Code
-- Plugin enable: Components become available for use
-- No restart required: Changes take effect on next Claude Code session
-
-**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories
+Claude Code automatically discovers components when a plugin is enabled — no restart required, changes take effect on next session. Custom paths in `plugin.json` supplement (not replace) default directories.
 
 ## Best Practices
 
-### Organization
-
-1. **Logical grouping**: Group related components together
-   - Put test-related commands, agents, and skills together
-   - Create subdirectories in `scripts/` for different purposes
-
-2. **Minimal manifest**: Keep `plugin.json` lean
-   - Only specify custom paths when necessary
-   - Rely on auto-discovery for standard layouts
-   - Use inline configuration only for simple cases
-
-3. **Documentation**: Include README files
-   - Plugin root: Overall purpose and usage
-   - Component directories: Specific guidance
-   - Script directories: Usage and requirements
-
-### Naming
-
-1. **Consistency**: Use consistent naming across components
-   - If command is `test-runner`, name related agent `test-runner-agent`
-   - Match skill directory names to their purpose
-
-2. **Clarity**: Use descriptive names that indicate purpose
-   - Good: `api-integration-testing/`, `code-quality-checker.md`
-   - Avoid: `utils/`, `misc.md`, `temp.sh`
-
-3. **Length**: Balance brevity with clarity
-   - Commands: 2-3 words (`review-pr`, `run-ci`)
-   - Agents: Describe role clearly (`code-reviewer`, `test-generator`)
-   - Skills: Topic-focused (`error-handling`, `api-design`)
-
-### Portability
-
-1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths
-2. **Test on multiple systems**: Verify on macOS, Linux, Windows
-3. **Document dependencies**: List required tools and versions
-4. **Avoid system-specific features**: Use portable bash/Python constructs
-
-### Maintenance
-
-1. **Version consistently**: Update version in plugin.json for releases
-2. **Deprecate gracefully**: Mark old components clearly before removal
-3. **Document breaking changes**: Note changes affecting existing users
-4. **Test thoroughly**: Verify all components work after changes
+- **Minimal manifest**: Rely on auto-discovery for standard layouts; only specify custom paths when necessary.
+- **Consistent naming**: If a command is `test-runner`, name the related agent `test-runner-agent`. Match skill directory names to their purpose.
+- **Descriptive names**: Good: `api-integration-testing/`, `code-quality-checker.md`. Avoid: `utils/`, `misc.md`.
+- **Always use `${CLAUDE_PLUGIN_ROOT}`**: Never hardcode paths. Document external dependencies.
 
 ## Common Patterns