fix: single-line descriptions, spec-conforming names, and template-noise removal

.github/workflows/lint.yml

@@ -0,0 +1,16 @@
+name: skill-lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: python3 scripts/lint_skills.py

README.md

@@ -51,7 +51,7 @@ npx skills add full-stack-skills/java-skills --skill <skill-name>
 | `license-compliance-triage` | Evidence-backed dependency-license review that reduces scanner false positives, resolves multi-license expressions, binds decisions to exact versions, and separates conditional obligations from real blockers |
 | `unirest-java-3` | Unirest 3.x HTTP client for Java 8+ with Apache HttpClient, built-in GSON, per-request proxy, mocking, caching, and connection pool tuning |
 | `unirest-java-4` | Unirest 4.x HTTP client for Java 11+ with java.net.http, SSE, WebSocket, HTTP/2, ProxySelector, mocking, caching, and modular JSON support |
-| `okhttp3-5.x` | OkHttp 5.x HTTP client for Java/JVM 8+ and Android 5+ with HTTP/2, transparent GZIP, Fast Fallback, MockWebServer, and GraalVM Native Image support |
+| `okhttp5` | OkHttp 5.x HTTP client for Java/JVM 8+ and Android 5+ with HTTP/2, transparent GZIP, Fast Fallback, MockWebServer, and GraalVM Native Image support |
 | `sa-token` | Sa-Token core authentication framework — login, permission/role auth, annotation auth, route interceptor, session management, token configuration, front-back separation |
 | `sa-token-advanced` | Sa-Token advanced security — secondary auth (2FA), account banning (full/category/tiered), identity switching, multi-account systems, global listener & filter, password encryption, HTTP Basic/Digest |
 | `sa-token-sso` | Sa-Token SSO single sign-on — 3 modes (same-domain cookie, cross-domain redirect, cross-domain HTTP ticket), SSO-Server setup, SSO-Client integration, single logout |

README.zh-CN.md

@@ -51,7 +51,7 @@ npx skills add full-stack-skills/java-skills --skill <skill-name>
 | `license-compliance-triage` | 基于证据的依赖许可证分诊，压降扫描误报、解析多许可证表达式、将结论绑定精确版本，并区分附带义务与真实阻断 |
 | `unirest-java-3` | Unirest 3.x HTTP 客户端，基于 Apache HttpClient，支持 Java 8+，内置 GSON，支持每请求代理、Mock 测试、缓存和连接池调优 |
 | `unirest-java-4` | Unirest 4.x HTTP 客户端，基于 java.net.http，支持 Java 11+，SSE、WebSocket、HTTP/2、ProxySelector、Mock 测试、缓存和模块化 JSON 支持 |
-| `okhttp3-5.x` | OkHttp 5.x HTTP 客户端，支持 Java/JVM 8+ 和 Android 5+，HTTP/2、透明 GZIP、Fast Fallback、MockWebServer、GraalVM Native Image 支持 |
+| `okhttp5` | OkHttp 5.x HTTP 客户端，支持 Java/JVM 8+ 和 Android 5+，HTTP/2、透明 GZIP、Fast Fallback、MockWebServer、GraalVM Native Image 支持 |
 | `sa-token` | Sa-Token 核心权限认证框架 — 登录认证、权限/角色认证、注解鉴权、路由拦截鉴权、Session 会话管理、框架配置、前后端分离 |
 | `sa-token-advanced` | Sa-Token 高级安全特性 — 二级认证、账号封禁(全/分类/阶梯)、身份切换、多账号体系(StpUserUtil/StpKit)、全局侦听器与过滤器、密码加密、Http Basic/Digest |
 | `sa-token-sso` | Sa-Token SSO 单点登录 — 三种模式(同域Cookie/跨域重定向/跨域Http ticket)、Server 搭建、Client 接入、单点注销、前后端分离 H5 方案 |

scripts/lint_skills.py

@@ -0,0 +1,72 @@
+"""Lint gate for skill packages: every skills/<name>/SKILL.md must be well-formed.
+
+Rules (exit 1 on any violation):
+- every directory under skills/ contains SKILL.md
+- frontmatter has a `name` equal to its directory name
+- `description` is present, single-line (block scalars break some hosts), 20-1024 chars
+- skill names are lowercase kebab-case without a `codex-` prefix
+"""
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def frontmatter(text: str) -> dict:
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    fields = {}
+    for line in text[4:end].splitlines():
+        if line and not line.startswith(" ") and ":" in line:
+            key, _, value = line.partition(":")
+            fields[key.strip()] = value.strip()
+        elif line.startswith(" ") or line.startswith("-"):
+            # continuation of a block scalar or list: mark parent as multiline
+            if fields:
+                last = next(reversed(fields))
+                fields[last] = fields[last] + "\n" + line
+    return fields
+
+
+def main() -> int:
+    errors = []
+    skills_dir = ROOT / "skills"
+    dirs = sorted(p for p in skills_dir.iterdir() if p.is_dir())
+    if not dirs:
+        errors.append("skills/ has no skill directories")
+    for skill_dir in dirs:
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            errors.append(f"{skill_dir.name}: missing SKILL.md")
+            continue
+        fm = frontmatter(skill_md.read_text())
+        name = fm.get("name", "")
+        desc = fm.get("description", "")
+        if not name:
+            errors.append(f"{skill_dir.name}: frontmatter missing name")
+        elif name != skill_dir.name:
+            errors.append(f"{skill_dir.name}: name '{name}' != directory name")
+        if not NAME_RE.match(skill_dir.name):
+            errors.append(f"{skill_dir.name}: not lowercase kebab-case")
+        if skill_dir.name.startswith("codex-"):
+            errors.append(f"{skill_dir.name}: host-prefixed names are not allowed in source packages")
+        if not desc:
+            errors.append(f"{skill_dir.name}: frontmatter missing description")
+        else:
+            if "\n" in desc or desc in ("|", ">", "|-", ">-", "|+", ">+"):
+                errors.append(f"{skill_dir.name}: description must be single-line (no block scalars)")
+            elif not (20 <= len(desc) <= 1024):
+                errors.append(f"{skill_dir.name}: description length {len(desc)} outside 20..1024")
+    for error in errors:
+        print(f"ERROR: {error}")
+    print(f"lint_skills: {len(dirs)} skills, {len(errors)} errors")
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skills/caffeine-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: caffeine-patterns
-description: |
-  Caffeine JVM 本地缓存技能。覆盖本地缓存 vs 远程缓存(Redis)选择决策树、expireAfterWrite vs expireAfterAccess vs refreshAfterWrite 三种过期策略对比与组合规则(refresh < expire)、CacheLoader加载与reload异步刷新模式、Spring Cache @Cacheable集成、maximumSize驱逐策略、recordStats缓存统计。
-  纠正 LLM：用 ConcurrentHashMap+手动过期、所有缓存走Redis、refreshAfterWrite > expireAfterWrite导致永远不刷新、CacheLoader返回null导致缓存穿透。
+description: Caffeine JVM 本地缓存技能。覆盖本地缓存 vs 远程缓存(Redis)选择决策树、expireAfterWrite vs expireAfterAccess vs refreshAfterWrite 三种过期策略对比与组合规则(refresh < expire)、CacheLoader加载与reload异步刷新模式、Spring Cache @Cacheable集成、maximumSize驱逐策略、recordStats缓存统计。 纠正 LLM：用 ConcurrentHashMap+手动过期、所有缓存走Redis、refreshAfterWrite > expireAfterWrite导致永远不刷新、CacheLoader返回null导致缓存穿透。
 license: Apache-2.0
 ---
 

skills/commons-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: commons-patterns
-description: |
-  Apache Commons 最佳实践模式。从官方文档提炼，覆盖 Commons Lang3(StringUtils千面判空/isEmpty vs isBlank/Validate抛NullPointerException迁移)、Commons IO(IOUtils.toString大文件陷阱/FileUtils.lineIterator逐行读模式/FilenameUtils.normalize路径规范化)、Commons Collections4(CollectionUtils.union/intersection/subtract集合运算)。
-  纠正 LLM 误用：混淆 StringUtils.isBlank vs isEmpty、IOUtils.toString 读大文件OOM、不知道 LineIterator 逐行读模式、用 lang 而非 lang3 包名。
+description: Apache Commons 最佳实践模式。从官方文档提炼，覆盖 Commons Lang3(StringUtils千面判空/isEmpty vs isBlank/Validate抛NullPointerException迁移)、Commons IO(IOUtils.toString大文件陷阱/FileUtils.lineIterator逐行读模式/FilenameUtils.normalize路径规范化)、Commons Collections4(CollectionUtils.union/intersection/subtract集合运算)。 纠正 LLM 误用：混淆 StringUtils.isBlank vs isEmpty、IOUtils.toString 读大文件OOM、不知道 LineIterator 逐行读模式、用 lang 而非 lang3 包名。
 license: Apache-2.0
 ---
 

skills/guava-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: guava-patterns
-description: |
-  Google Guava 最佳实践模式。从官方 wiki 提炼，覆盖 Immutable集合的 of/copyOf/builder 三模式与防御性拷贝规则、Cache 选择决策(LoadingCache vs Cache vs Caffeine)、Joiner/Splitter 不可变流水线、CharMatcher 替代正则、Preconditions 格式化消息校验、CaseFormat 命名互转。
-  纠正 LLM 误用：手写不可变集合、ConcurrentHashMap 替代 Cache、不知 CharMatcher。
+description: Google Guava 最佳实践模式。从官方 wiki 提炼，覆盖 Immutable集合的 of/copyOf/builder 三模式与防御性拷贝规则、Cache 选择决策(LoadingCache vs Cache vs Caffeine)、Joiner/Splitter 不可变流水线、CharMatcher 替代正则、Preconditions 格式化消息校验、CaseFormat 命名互转。 纠正 LLM 误用：手写不可变集合、ConcurrentHashMap 替代 Cache、不知 CharMatcher。
 license: Apache-2.0
 ---
 

skills/hutool-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: hutool-patterns
-description: |
-  Hutool 中文 Java 工具库技能。覆盖与 Guava/Apache Commons 的功能选择矩阵、字符串/集合/日期/文件/HTTP 最常用方法速查、HttpUtil vs OkHttp 选型、BeanUtil vs MapStruct 职责划分。
-  当用户在 Java 项目中需要中文场景的工具方法(拼音/身份证/手机号校验)、HTTP请求、文件操作、加解密时使用。避免 LLM 自造轮子而不用 Hutool。
+description: Hutool 中文 Java 工具库技能。覆盖与 Guava/Apache Commons 的功能选择矩阵、字符串/集合/日期/文件/HTTP 最常用方法速查、HttpUtil vs OkHttp 选型、BeanUtil vs MapStruct 职责划分。 当用户在 Java 项目中需要中文场景的工具方法(拼音/身份证/手机号校验)、HTTP请求、文件操作、加解密时使用。避免 LLM 自造轮子而不用 Hutool。
 license: Apache-2.0
 ---
 

skills/jackson-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: jackson-patterns
-description: |
-  Jackson JSON 序列化技能。覆盖日期格式配置(非ISO-8601)、Null序列化规则(数组→[]/字符串→""/数字→null)、@JsonView分层、ObjectMapper单例规则、TypeReference泛型反序列化、@JsonProperty/@JsonFormat/@JsonIgnore注解原则、与Spring Boot集成。
-  当用户处理JSON序列化/反序列化、配置ObjectMapper、解决日期格式或null处理问题时使用。
+description: Jackson JSON 序列化技能。覆盖日期格式配置(非ISO-8601)、Null序列化规则(数组→[]/字符串→""/数字→null)、@JsonView分层、ObjectMapper单例规则、TypeReference泛型反序列化、@JsonProperty/@JsonFormat/@JsonIgnore注解原则、与Spring Boot集成。 当用户处理JSON序列化/反序列化、配置ObjectMapper、解决日期格式或null处理问题时使用。
 license: Apache-2.0
 ---
 

skills/java-code-comments/SKILL.md

@@ -1,13 +1,6 @@
 ---
 name: java-code-comments
-description: |
-  Provides comprehensive guidance for adding Java code comments following industry standards and best practices. 
-  This skill helps add class-level comments, method-level comments, and field-level comments to Java code. 
-  Use when the user wants to add comments to Java code, needs to document Java classes/methods/fields, 
-  wants to improve code documentation, or needs to generate JavaDoc comments. This skill covers Controller, 
-  Service, ServiceImpl, Mapper, Model, Entity, BO (Business Object), DTO, VO, and other common Java 
-  component types. The skill follows a systematic workflow: scan codebase, identify components, create 
-  todo list, and add comments in order (class comments → method comments → field comments).
+description: "Provides comprehensive guidance for adding Java code comments following industry standards and best practices. This skill helps add class-level comments, method-level comments, and field-level comments to Java code. Use when the user wants to add comments to Java code, needs to document Java classes/methods/fields, wants to improve code documentation, or needs to generate JavaDoc comments. This skill covers Controller, Service, ServiceImpl, Mapper, Model, Entity, BO (Business Object), DTO, VO, and other common Java component types. The skill follows a systematic workflow: scan codebase, identify components, create todo list, and add comments in order (class comments → method comments → field comments)."
 license: Apache-2.0
 ---
 

skills/java-component-patterns/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: java-component-patterns
-description: |
-  Java 组件（SDK/工具库，非 Spring Boot starter）封装规范。无 parent 独立 POM 结构、licenses/scm/developers 元数据三段、三段式 properties（基础/Dependency versions/Plugin versions 自然排序）、Jackson BOM 统一版本管理、maven.compiler.release 的 API 安全用法、多 JDK 分支模型（feature/{line} → JDK 8/17/21）、组件间同线依赖、tag 发布与 SNAPSHOT 滚动、JaCoCo 90% 门禁、pom.xml 4 空格缩进格式化。
-  纠正 LLM：给独立组件加 spring-boot-starter-parent、java.version 写 8（应写 1.8）、properties 不分类不排序、漏 licenses/scm/developers 导致 Central 被拒、跨线依赖内部组件（1.0.x 依赖 2.0.x）、忘记无 parent 需自管全部插件版本、Jackson 依赖在 dm 中放无 version 条目遮蔽 BOM、License URL 用 http（应用 https）。
-  触发词：组件封装、SDK 开发、无 parent pom、独立库、java component、多 JDK 分支、xxx-java-sdk 模板、jackson-bom、Jackson 版本管理。
+description: Java 组件（SDK/工具库，非 Spring Boot starter）封装规范。无 parent 独立 POM 结构、licenses/scm/developers 元数据三段、三段式 properties（基础/Dependency versions/Plugin versions 自然排序）、Jackson BOM 统一版本管理、maven.compiler.release 的 API 安全用法、多 JDK 分支模型（feature/{line} → JDK 8/17/21）、组件间同线依赖、tag 发布与 SNAPSHOT 滚动、JaCoCo 90% 门禁、pom.xml 4 空格缩进格式化。 纠正 LLM：给独立组件加 spring-boot-starter-parent、java.version 写 8（应写 1.8）、properties 不分类不排序、漏 licenses/scm/developers 导致 Central 被拒、跨线依赖内部组件（1.0.x 依赖 2.0.x）、忘记无 parent 需自管全部插件版本、Jackson 依赖在 dm 中放无 version 条目遮蔽 BOM、License URL 用 http（应用 https）。 触发词：组件封装、SDK 开发、无 parent pom、独立库、java component、多 JDK 分支、xxx-java-sdk 模板、jackson-bom、Jackson 版本管理。
 license: Apache-2.0
 ---
 

skills/java-development-manual/SKILL.md

@@ -1,13 +1,8 @@
 ---
 name: java-development-manual
 license: Apache-2.0
-description: |
-  Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。
-  涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。
-  当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设计 (7) 工程架构设计时使用此skill。
-  触发词：Java规范、阿里规约、代码规范、开发手册、编程规约、异常处理、单元测试、安全、MySQL、工程结构、设计模式。
+description: Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设计 (7) 工程架构设计时使用此skill。 触发词：Java规范、阿里规约、代码规范、开发手册、编程规约、异常处理、单元测试、安全、MySQL、工程结构、设计模式。
 ---
-
 # Java开发手册（嵩山版）
 
 ## 概述
@@ -158,42 +153,3 @@ try {
 2. **性能问题** → 查看 [mysql.md](references/mysql.md) 的"索引规约"
 3. **并发问题** → 查看 [coding-convention.md](references/coding-convention.md) 的"并发处理"
 
-## 能力边界
-
-### ✅ 适用场景
-- 当你需要使用此技能对应的技术栈时
-- 当项目需要遵循最佳实践时
-- 当需要快速上手或深入理解核心概念时
-
-### ⚠️ 需要注意
-- 复杂业务逻辑需要结合具体场景调整
-- 性能优化需要根据实际数据量评估
-
-### ❌ 不适用场景
-- 不相关的技术栈或框架
-- 需要完全自定义的特殊场景
-
-## 常见陷阱 (Gotchas)
-
-1. **版本兼容性**：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
-2. **配置文件格式**：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
-3. **环境变量**：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
-4. **依赖冲突**：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
-5. **性能陷阱**：大数据量场景下注意性能优化，避免 N+1 查询等常见问题
-
-## 使用流程
-
-### Step 1: 环境准备
-确保开发环境已安装必要的依赖和工具。
-
-### Step 2: 配置初始化
-根据项目需求进行基础配置。
-
-### Step 3: 核心功能使用
-按照示例代码实现核心功能。
-
-### Step 4: 测试验证
-运行测试确保功能正常。
-
-### Step 5: 部署上线
-完成开发后进行部署和监控。

skills/junit-mockito-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: junit-mockito-patterns
-description: |
-  JUnit5 + Mockito 测试框架技能。覆盖 JUnit5 @ExtendWith替代@RunWith、Mockito @Mock/@InjectMocks规则、测试隔离原则(FIRST)、@SpringBootTest何时用何时不用(@WebMvcTest/@DataJpaTest切片测试)、BDDMockito given/willReturn风格、ArgumentCaptor参数捕获、verify行为验证、@ParameterizedTest参数化测试。
-  当用户编写 Java 单元测试/集成测试、Mock外部依赖时需要此技能。
+description: JUnit5 + Mockito 测试框架技能。覆盖 JUnit5 @ExtendWith替代@RunWith、Mockito @Mock/@InjectMocks规则、测试隔离原则(FIRST)、@SpringBootTest何时用何时不用(@WebMvcTest/@DataJpaTest切片测试)、BDDMockito given/willReturn风格、ArgumentCaptor参数捕获、verify行为验证、@ParameterizedTest参数化测试。 当用户编写 Java 单元测试/集成测试、Mock外部依赖时需要此技能。
 license: Apache-2.0
 ---
 

skills/kafka-patterns/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: kafka-patterns
-description: |
-  Apache Kafka 消息队列技能。覆盖生产者 acks=all/1/0 选择决策、幂等性(enable.idempotence + acks=all)配置、消费者手动提交 offset(enable.auto.commit=false)、DLT死信处理(@RetryableTopic/@DltHandler)、@KafkaListener + 异常处理器(DefaultErrorHandler)、顺序消息(同一Key发同一分区)、事务消息。
-  纠正 LLM：acks=0 丢消息、auto.commit 漏消息、不处理重复消费、不配置 DLT。
+description: Apache Kafka 消息队列技能。覆盖生产者 acks=all/1/0 选择决策、幂等性(enable.idempotence + acks=all)配置、消费者手动提交 offset(enable.auto.commit=false)、DLT死信处理(@RetryableTopic/@DltHandler)、@KafkaListener + 异常处理器(DefaultErrorHandler)、顺序消息(同一Key发同一分区)、事务消息。 纠正 LLM：acks=0 丢消息、auto.commit 漏消息、不处理重复消费、不配置 DLT。
 license: Apache-2.0
 ---