feat: improve skill UX and add v2.2.0 improvements

ducpm2303 · claude · ducpm2303 · commit 7e6926261252 · 2026-04-03T21:57:56.000+07:00
- Add explicit trigger phrases to all skill descriptions for better auto-invocation
- Add allowed-tools frontmatter to read-only skills (review, explain, health, etc.)
- Add SessionStart hook to java-core (detects Java version on session open)
- Add PreToolUse and Stop hooks to java-quality (warns on dangerous commands, reminds to run tests)
- Refactor java-crud SKILL.md: move inline templates to references/templates.md
- Refactor java-scaffold SKILL.md: move inline templates to references/templates.md
- Bump all plugins to v2.2.0

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,28 +5,28 @@
   },
   "metadata": {
     "description": "Java developer toolkit for Claude Code — general Java, Spring Boot, and quality (security + performance + testing)",
-    "version": "2.1.0"
+    "version": "2.2.0"
   },
   "plugins": [
     {
       "name": "java-core",
       "source": "./plugins/java-core",
       "description": "General Java skills (review, refactor, explain, fix, docs, health, concurrency, API, migration, commit, SOLID, design patterns, ADR) and architect + build-resolver agents",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "keywords": ["java", "core", "review", "refactor", "solid", "design-patterns", "concurrency", "migrate", "adr"]
     },
     {
       "name": "java-spring",
       "source": "./plugins/java-spring",
       "description": "Spring Boot skills (scaffold new projects, JPA review, logging review, CRUD generator) and Spring expert agent. Supports Spring Boot 2.7.x through 4.0.x.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "keywords": ["java", "spring", "spring-boot", "scaffold", "jpa", "crud", "logging"]
     },
     {
       "name": "java-quality",
       "source": "./plugins/java-quality",
       "description": "Java quality toolkit — security scan (/java-security-check), performance scan (/java-perf-check), test generation (/java-test), and specialist agents for OWASP, performance, and testing strategy",
-      "version": "1.0.0",
+      "version": "2.2.0",
       "keywords": ["java", "security", "owasp", "performance", "testing", "junit", "mockito", "testcontainers"]
     }
   ]
diff --git a/plugins/java-core/.claude-plugin/plugin.json b/plugins/java-core/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "java-core",
   "description": "General Java skills, architect agent, and coding standards for Java 8+",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": {
     "name": "java-plugins contributors"
   },
diff --git a/plugins/java-core/hooks/hooks.json b/plugins/java-core/hooks/hooks.json
@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[java-core] Detecting Java project...' && (cat pom.xml 2>/dev/null | grep -E '<java.version>|<maven.compiler.source>' | head -2 || cat build.gradle 2>/dev/null | grep -E 'sourceCompatibility|JavaVersion' | head -2 || echo '[java-core] No build file found — ask user for Java version if needed.')"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
diff --git a/plugins/java-core/skills/java-adr/SKILL.md b/plugins/java-core/skills/java-adr/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Create, list, or update Architecture Decision Records (ADRs) for your Java project
+description: Creates, lists, and manages Architecture Decision Records for Java projects. Use when user asks to "create an ADR", "document this decision", "write an architecture decision", "add ADR", "list decisions", "show ADRs", or "record this architectural choice".
 argument-hint: "[new <title> | list | show <id> | supersede <id> <title>]"
 ---
 
diff --git a/plugins/java-core/skills/java-api-review/SKILL.md b/plugins/java-core/skills/java-api-review/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Review Java REST API design — HTTP status codes, naming, pagination, versioning, error responses, and validation
+description: Reviews Java REST API design including HTTP methods, status codes, naming, and versioning. Use when user asks to "review my API", "check REST design", "is this good REST", "review endpoints", "API design review", "check my controller", or "review HTTP API".
 argument-hint: "[paste controller or API code]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Review the REST API design of the provided Java controller or endpoint code. Detect Spring Boot version from `pom.xml` to tailor advice.
diff --git a/plugins/java-core/skills/java-commit/SKILL.md b/plugins/java-core/skills/java-commit/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Generate a meaningful git commit message based on the Java files changed
+description: Generates a Conventional Commits message for staged Java changes. Use when user asks to "write a commit message", "help me commit", "what should my commit say", "summarize my changes", "draft a commit", or "create commit message".
 argument-hint: "[leave empty to use git diff, or describe the change]"
 ---
 
diff --git a/plugins/java-core/skills/java-concurrency-review/SKILL.md b/plugins/java-core/skills/java-concurrency-review/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Review Java code for thread safety issues, race conditions, deadlocks, and concurrency anti-patterns
+description: Reviews Java code for thread safety, race conditions, deadlocks, and Java 21 virtual thread compatibility. Use when user asks to "review concurrency", "is this thread safe", "check for race conditions", "concurrency issues", or "virtual thread compatible".
 argument-hint: "[paste concurrent code or select in editor]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Review the Java code for concurrency correctness. Before reviewing, detect the Java version from `pom.xml` or `build.gradle` — suggest modern alternatives only if the version supports them.
diff --git a/plugins/java-core/skills/java-design-pattern/SKILL.md b/plugins/java-core/skills/java-design-pattern/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Detect design patterns in Java code, or suggest the right pattern for a given problem
+description: Detects GoF patterns in Java code or recommends the right pattern for a problem. Use when user asks to "what pattern is this", "detect design patterns", "suggest a pattern", "should I use factory", "which design pattern", or "recommend a pattern for".
 argument-hint: "[paste code to detect patterns, or describe your problem]"
 ---
 
diff --git a/plugins/java-core/skills/java-docs/SKILL.md b/plugins/java-core/skills/java-docs/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Generate Javadoc comments for selected Java classes and methods
+description: Generates Javadoc comments for Java classes and methods. Use when user asks to "add javadoc", "document this class", "write documentation", "add comments", "generate docs", or "document this method".
 argument-hint: "[paste code or select in editor]"
 ---
 
diff --git a/plugins/java-core/skills/java-explain/SKILL.md b/plugins/java-core/skills/java-explain/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Explain selected Java code in plain language, including design patterns and idioms used
+description: Explains Java code in plain language including design patterns. Use when user asks to "explain this code", "what does this do", "help me understand", "walk me through this", or "how does this work".
 argument-hint: "[paste code or select in editor]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Explain the Java code I've selected or provided. Tailor the explanation to what the code actually does — avoid generic descriptions.
diff --git a/plugins/java-core/skills/java-fix/SKILL.md b/plugins/java-core/skills/java-fix/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Diagnose Java compile errors or stack traces and propose a targeted fix
+description: Diagnoses and fixes Java compile errors, runtime exceptions, and stack traces. Use when user asks to "fix this error", "this won't compile", "I'm getting an exception", "debug this", or "build is failing".
 argument-hint: "[paste error message or stack trace]"
 ---
 
diff --git a/plugins/java-core/skills/java-health/SKILL.md b/plugins/java-core/skills/java-health/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Run a holistic code health check across security, performance, test coverage, code smells, and dependency freshness
+description: Runs a holistic code health check scoring Security, Tests, Performance and Quality with A-F grades. Use when user asks to "check health", "score this project", "health check", "how good is this code", "overall assessment", or "code quality score".
 argument-hint: "[path to file, class, or leave empty for current project]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Run a comprehensive health check on the Java code or project I've indicated. This is an aggregating command — it runs multiple review dimensions and produces a single scored report.
diff --git a/plugins/java-core/skills/java-migrate/SKILL.md b/plugins/java-core/skills/java-migrate/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Interactive guide to upgrade your Java project from one version to another (8→11, 11→17, 17→21)
+description: Interactive Java version upgrade guide (8 to 11, 11 to 17, 17 to 21). Use when user asks to "migrate to Java 17", "upgrade to Java 21", "Java migration guide", "move from Java 11 to 17", or "what changed in Java 21".
 argument-hint: "[current Java version and target version, e.g. '8 to 17']"
 ---
 
diff --git a/plugins/java-core/skills/java-refactor/SKILL.md b/plugins/java-core/skills/java-refactor/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Suggest and apply version-appropriate refactorings to Java code
+description: Suggests and applies version-gated Java refactorings. Use when user asks to "refactor this", "clean up this code", "modernize this Java", "simplify this", "extract method", "improve this class", or "make this more idiomatic".
 argument-hint: "[paste code or select in editor]"
 ---
 
diff --git a/plugins/java-core/skills/java-review/SKILL.md b/plugins/java-core/skills/java-review/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Review Java code for bugs, naming issues, code smells, and version-appropriate idioms
+description: Reviews Java code for bugs, naming issues, code smells, and version-appropriate idioms. Use when user asks to "review this code", "check my Java", "look at this class", "find issues in", "code review", "what's wrong with this", or "review this file".
 argument-hint: "[paste code or select in editor]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Review the Java code I've selected or provided. Follow these steps:
diff --git a/plugins/java-core/skills/java-solid/SKILL.md b/plugins/java-core/skills/java-solid/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Check Java code for SOLID principles violations and suggest improvements
+description: Checks Java code for SOLID principles violations with Java-specific patterns. Use when user asks to "check SOLID principles", "is this good OOP", "single responsibility", "SOLID violations", "open closed principle", or "dependency inversion".
 argument-hint: "[paste class or paste multiple related classes]"
+allowed-tools: Read, Grep, Glob
 ---
 
 Review the provided Java code for SOLID principles violations. For each principle, check for violations and suggest targeted improvements. Tailor suggestions to the detected Java version.
diff --git a/plugins/java-quality/.claude-plugin/plugin.json b/plugins/java-quality/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "java-quality",
   "description": "Java quality toolkit — security (OWASP), performance (N+1, memory, threading), and testing (JUnit 5, Mockito, Testcontainers) for Java 8+ projects",
-  "version": "1.0.0",
+  "version": "2.2.0",
   "author": {
     "name": "java-plugins contributors"
   },
diff --git a/plugins/java-quality/hooks/hooks.json b/plugins/java-quality/hooks/hooks.json
@@ -1,12 +1,33 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"$CLAUDE_TOOL_INPUT\" | python3 -c \"\nimport sys, json, re\ntry:\n    data = json.load(sys.stdin)\n    cmd = data.get('command', '')\n    dangerous = [\n        (r'git push.*--force.*(main|master)', 'Force push to main/master branch'),\n        (r'git reset --hard', 'Hard reset (discards uncommitted changes)'),\n        (r'mvn.*-Dmaven.test.skip=true', 'Skipping tests in Maven build'),\n        (r'./gradlew.*-x test', 'Skipping tests in Gradle build'),\n    ]\n    for pattern, msg in dangerous:\n        if re.search(pattern, cmd):\n            print(f'[java-quality] WARNING: {msg}: {cmd}', flush=True)\nexcept: pass\n\""
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "echo '[java-quality] Java file modified. Consider asking the java-security-reviewer agent to check for OWASP vulnerabilities, or run /java-security-check for a quick scan.'"
+            "command": "echo '[java-quality] Java file modified. Consider running /java-security-check or asking the java-security-reviewer agent to check for OWASP vulnerabilities.'"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[java-quality] Session ending. Reminder: run mvn test or ./gradlew test to verify all tests pass before considering this task complete.'"
           }
         ]
       }
diff --git a/plugins/java-quality/skills/java-perf-check/SKILL.md b/plugins/java-quality/skills/java-perf-check/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Quick performance scan of Java code — flags N+1 queries, memory inefficiencies, threading issues, and algorithmic hotspots
+description: Quick Java performance scan flagging N+1 queries, memory issues, threading problems, and algorithmic hotspots. Use when user asks to "check performance", "performance scan", "any N+1 queries", "performance issues", "is this efficient", or "slow code".
 argument-hint: "[file or class to scan, optional]"
+allowed-tools: Read, Grep, Glob
 ---
 
 # /java-perf-check — Java Performance Quick Scan
diff --git a/plugins/java-quality/skills/java-security-check/SKILL.md b/plugins/java-quality/skills/java-security-check/SKILL.md
@@ -1,6 +1,7 @@
 ---
-description: Quick OWASP security scan of Java code — flags injection risks, hardcoded secrets, weak crypto, and Spring Security misconfigs
+description: Quick OWASP security scan for injection risks, hardcoded secrets, weak crypto, and Spring Security misconfigs. Use when user asks to "security scan", "check for vulnerabilities", "any security issues", "OWASP check", "hardcoded secrets", or "is this secure".
 argument-hint: "[file or class to scan, optional]"
+allowed-tools: Read, Grep, Glob
 ---
 
 # /java-security-check — Java Security Quick Scan
diff --git a/plugins/java-quality/skills/java-test/SKILL.md b/plugins/java-quality/skills/java-test/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Generate JUnit 5 + Mockito unit tests or Testcontainers integration tests for Java code
+description: Generates JUnit 5 and Mockito unit tests or Testcontainers integration tests, auto-detecting project setup. Use when user asks to "write tests", "generate tests", "add unit tests", "create test class", "test this service", or "write integration tests".
 argument-hint: "[paste the class to test, or describe what to test]"
 ---
 
diff --git a/plugins/java-spring/.claude-plugin/plugin.json b/plugins/java-spring/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "java-spring",
   "description": "Spring Boot scaffold skill and Spring expert agent for Java 8+ projects",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": {
     "name": "java-plugins contributors"
   },
diff --git a/plugins/java-spring/skills/java-crud/SKILL.md b/plugins/java-spring/skills/java-crud/SKILL.md
diff --git a/plugins/java-spring/skills/java-crud/references/templates.md b/plugins/java-spring/skills/java-crud/references/templates.md
diff --git a/plugins/java-spring/skills/java-jpa/SKILL.md b/plugins/java-spring/skills/java-jpa/SKILL.md
diff --git a/plugins/java-spring/skills/java-logging/SKILL.md b/plugins/java-spring/skills/java-logging/SKILL.md
diff --git a/plugins/java-spring/skills/java-scaffold/SKILL.md b/plugins/java-spring/skills/java-scaffold/SKILL.md
diff --git a/plugins/java-spring/skills/java-scaffold/references/templates.md b/plugins/java-spring/skills/java-scaffold/references/templates.md

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "java-core",`
`3`	`3`	`"description": "General Java skills, architect agent, and coding standards for Java 8+",`
`4`		`- "version": "2.1.0",`
	`4`	`+ "version": "2.2.0",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "java-plugins contributors"`
`7`	`7`	`},`