@ohos-cpf/3rdloop 0.0.2 → 0.0.3

package/vendor/Server/Skills/rn-library-documentation-quality-check/references/GOTCHAS.md

@@ -1,57 +1,57 @@
-# 常见陷阱（Gotchas）
-
-> 本文件记录 `rn-library-documentation-quality-check` 技能在检视过程中容易踩坑的场景和注意事项。
-
----
-
-## 一、接口与命名陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **TurboModule Spec 接口归零判定** | `.d.ts` 中 `Spec extends TurboModule` 接口完全无注释时触发归零，但若 README 有该 API 的用法说明则不触发——需同时检查源码注释和 README 描述 | 归零规则误判 |
-| **`delete` 是 JS 保留字** | 源码 `export { delete }` 合法，README 可能写作 `axios.delete()` 或 `axios.del()` | 方法名比对误报 |
-| **命名导出 vs 默认导出** | `export { lottie }` 是命名导出，示例必须用 `import { lottie }` 而非 `import lottie`，这是最常见的示例 Blocker | 示例质量误判 |
-| **`@react-native-ohos/` 前缀** | 鸿蒙化包名通常以 `@react-native-ohos/` 开头，README 示例可能使用原库名导致 import 路径错误 | 示例 import 检查 |
-
-## 二、ArkTS 与鸿蒙特有陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **ArkTS 严格模式** | ArkTS 比 TS 更严格（不允许 `any`、强制类型标注），示例代码需以 ArkTS 规范为准 | 示例质量评估偏差 |
-| **Codegen 配置** | TurboModule 库需在 `react-native.config.js` 中配置 Codegen，该文件无说明是常见遗漏 | 适配说明遗漏 |
-| **module.json5 不是 JSON** | 允许注释和尾逗号，不能按严格 JSON 解析 | 解析报错 |
-
-## 三、版本与变更陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **版本号多处不一致** | package.json、oh-package.json5、README、CHANGELOG 中的版本号可能不一致，需交叉对比 | 版本规范误判 |
-| **CHANGELOG 未记录鸿蒙化变更** | CHANGELOG 存在但仅含原库版本历史，无鸿蒙化适配条目是常见遗漏 | 变更记录遗漏 |
-| **文档描述的 API 可能是旧版签名** | 代码重构后 API 签名变更但文档未同步更新，这是最常见的准确性问题，必须通过交叉验证环节发现 | 交叉验证遗漏 |
-
-## 四、异步与类型陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **async/Promise 返回类型遗漏** | 文档写 `getConfig(): Config` 但代码实际为 `getConfig(): Promise<Config>`，这是最常见的签名不一致模式 | 签名比对误报 |
-| **示例代码未处理异步** | TurboModule 方法多为 Promise 返回，示例未 await 是常见 Major 问题 | 示例质量扣分 |
-| **可选参数差异** | 文档写 `callback: Function` 但代码签名 `callback?: Function`（可选性未标注），或反向文档标注可选但代码实际必选 | 参数比对误报 |
-
-## 五、跳转文档模式陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **跳转文档模式误判为"文档缺失"** | 跳转模式的 README 极简是设计选择，不应直接扣分为 RM-002/RM-004，应转而检视外部 usage-docs 内容完整性 | 评分严重偏差 |
-| **跳转文档链接指向统一仓库** | `OpenHarmony-RN/usage-docs` 是集中式文档仓库，一个库的文档对应 `zh-cn/{库名}.md` 和 `en/{库名}.md`，需分别获取中英文版本 | 文档获取遗漏 |
-| **跳转文档可能未同步更新** | usage-docs 仓库的文档可能滞后于代码仓库更新，需通过 Phase 2.5 交叉验证环节强制比对（XC-001/XC-006） | 文档过时未发现 |
-| **跳转文档的库名映射** | URL 中的库名是原库名（如 `react-native-network-info`），不是鸿蒙化包名（如 `@react-native-ohos/react-native-network-info`），提取时需去掉 `@org/` 前缀和版本号 | URL 构造错误 |
-| **跳转文档接口支持矩阵过时** | 外部 usage-docs 的 Yes/No/Partial 标记可能基于旧版代码，需与接口规格说明文档中的鸿蒙化差异（第 5 章）逐项比对 | 支持矩阵不准 |
-| **rndocUrl 优先使用** | 当任务参数传入 rndocUrl 时，跳转模式下应优先使用 rndocUrl 下载文档，而非从 README 提取链接或构造标准 URL。rndocUrl 通常是用户确认过的正确文档地址，可靠性最高 | 文档获取失败 |
-
-## 六、交叉验证陷阱
-
-| 陷阱 | 说明 | 影响 |
-|------|------|------|
-| **接口规格说明文档是权威基准** | 由 `RNLibraryInterfaceAnalyzer` 从上游原库和鸿蒙化仓库双仓库提取生成，已包含完整 API 清单和鸿蒙化差异，交叉验证时直接使用，无需再从源码逐条提取 | 重复工作 |
-| **接口规格说明文档缺失时无法交叉验证** | 若 `{outputDir}/接口规格说明.md` 不存在（前置 SKILL 未执行），记录为 XC-001 Critical，跳过交叉验证环节，在报告中注明 | 交叉验证跳过 |
-| **内嵌文档模板版本** | 内嵌模式的 README 通常遵循模板格式（如 `模板版本：v0.4.1`），可通过模板版本判断文档规范性 | 文档规范性判断 |
+# 常见陷阱（Gotchas）
+
+> 本文件记录 `rn-library-documentation-quality-check` 技能在检视过程中容易踩坑的场景和注意事项。
+
+---
+
+## 一、接口与命名陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **TurboModule Spec 接口归零判定** | `.d.ts` 中 `Spec extends TurboModule` 接口完全无注释时触发归零，但若 README 有该 API 的用法说明则不触发——需同时检查源码注释和 README 描述 | 归零规则误判 |
+| **`delete` 是 JS 保留字** | 源码 `export { delete }` 合法，README 可能写作 `axios.delete()` 或 `axios.del()` | 方法名比对误报 |
+| **命名导出 vs 默认导出** | `export { lottie }` 是命名导出，示例必须用 `import { lottie }` 而非 `import lottie`，这是最常见的示例 Blocker | 示例质量误判 |
+| **`@react-native-ohos/` 前缀** | 鸿蒙化包名通常以 `@react-native-ohos/` 开头，README 示例可能使用原库名导致 import 路径错误 | 示例 import 检查 |
+
+## 二、ArkTS 与鸿蒙特有陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **ArkTS 严格模式** | ArkTS 比 TS 更严格（不允许 `any`、强制类型标注），示例代码需以 ArkTS 规范为准 | 示例质量评估偏差 |
+| **Codegen 配置** | TurboModule 库需在 `react-native.config.js` 中配置 Codegen，该文件无说明是常见遗漏 | 适配说明遗漏 |
+| **module.json5 不是 JSON** | 允许注释和尾逗号，不能按严格 JSON 解析 | 解析报错 |
+
+## 三、版本与变更陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **版本号多处不一致** | package.json、oh-package.json5、README、CHANGELOG 中的版本号可能不一致，需交叉对比 | 版本规范误判 |
+| **CHANGELOG 未记录鸿蒙化变更** | CHANGELOG 存在但仅含原库版本历史，无鸿蒙化适配条目是常见遗漏 | 变更记录遗漏 |
+| **文档描述的 API 可能是旧版签名** | 代码重构后 API 签名变更但文档未同步更新，这是最常见的准确性问题，必须通过交叉验证环节发现 | 交叉验证遗漏 |
+
+## 四、异步与类型陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **async/Promise 返回类型遗漏** | 文档写 `getConfig(): Config` 但代码实际为 `getConfig(): Promise<Config>`，这是最常见的签名不一致模式 | 签名比对误报 |
+| **示例代码未处理异步** | TurboModule 方法多为 Promise 返回，示例未 await 是常见 Major 问题 | 示例质量扣分 |
+| **可选参数差异** | 文档写 `callback: Function` 但代码签名 `callback?: Function`（可选性未标注），或反向文档标注可选但代码实际必选 | 参数比对误报 |
+
+## 五、跳转文档模式陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **跳转文档模式误判为"文档缺失"** | 跳转模式的 README 极简是设计选择，不应直接扣分为 RM-002/RM-004，应转而检视外部 usage-docs 内容完整性 | 评分严重偏差 |
+| **跳转文档链接指向统一仓库** | `OpenHarmony-RN/usage-docs` 是集中式文档仓库，一个库的文档对应 `zh-cn/{库名}.md` 和 `en/{库名}.md`，需分别获取中英文版本 | 文档获取遗漏 |
+| **跳转文档可能未同步更新** | usage-docs 仓库的文档可能滞后于代码仓库更新，需通过 Phase 2.5 交叉验证环节强制比对（XC-001/XC-006） | 文档过时未发现 |
+| **跳转文档的库名映射** | URL 中的库名是原库名（如 `react-native-network-info`），不是鸿蒙化包名（如 `@react-native-ohos/react-native-network-info`），提取时需去掉 `@org/` 前缀和版本号 | URL 构造错误 |
+| **跳转文档接口支持矩阵过时** | 外部 usage-docs 的 Yes/No/Partial 标记可能基于旧版代码，需与接口规格说明文档中的鸿蒙化差异（第 5 章）逐项比对 | 支持矩阵不准 |
+| **rndocUrl 优先使用** | 当任务参数传入 rndocUrl 时，跳转模式下应优先使用 rndocUrl 下载文档，而非从 README 提取链接或构造标准 URL。rndocUrl 通常是用户确认过的正确文档地址，可靠性最高 | 文档获取失败 |
+
+## 六、交叉验证陷阱
+
+| 陷阱 | 说明 | 影响 |
+|------|------|------|
+| **接口规格说明文档是权威基准** | 由 `RNLibraryInterfaceAnalyzer` 从上游原库和鸿蒙化仓库双仓库提取生成，已包含完整 API 清单和鸿蒙化差异，交叉验证时直接使用，无需再从源码逐条提取 | 重复工作 |
+| **接口规格说明文档缺失时无法交叉验证** | 若 `{outputDir}/接口规格说明.md` 不存在（前置 SKILL 未执行），记录为 XC-001 Critical，跳过交叉验证环节，在报告中注明 | 交叉验证跳过 |
+| **内嵌文档模板版本** | 内嵌模式的 README 通常遵循模板格式（如 `模板版本：v0.4.1`），可通过模板版本判断文档规范性 | 文档规范性判断 |

package/vendor/Server/Skills/rn-library-documentation-quality-check/scripts/validate-skill.py

@@ -1,259 +1,259 @@
-#!/usr/bin/env python3
-# @tool validate-skill
-# @description 校验SKILL目录是否符合Agent Skills规范，检查frontmatter、结构、渐进式披露
-# @param skillDir: string - SKILL目录绝对路径
-
-import sys
-import json
-import os
-import re
-
-
-def main():
-    # 解析参数：支持 JSON 字符串（MCP Gateway 调用）或直接命令行参数
-    if len(sys.argv) > 1:
-        arg = sys.argv[1]
-        if arg.startswith('{'):
-            skill_dir = json.loads(arg).get('skillDir', '')
-        else:
-            skill_dir = arg
-    else:
-        print("Usage: validate-skill.py <skillDir>")
-        print("Error: skillDir parameter is required")
-        sys.exit(1)
-
-    if not skill_dir:
-        print("Usage: validate-skill.py <skillDir>")
-        print("Error: skillDir parameter is required")
-        sys.exit(1)
-
-    if not os.path.isdir(skill_dir):
-        print(f"Error: Directory does not exist: {skill_dir}")
-        sys.exit(1)
-
-    passed = 0
-    failed = 0
-    warnings = 0
-
-    def check_pass(msg):
-        nonlocal passed
-        print(f"  PASS  {msg}")
-        passed += 1
-
-    def check_fail(msg):
-        nonlocal failed
-        print(f"  FAIL  {msg}")
-        failed += 1
-
-    def check_warn(msg):
-        nonlocal warnings
-        print(f"  WARN  {msg}")
-        warnings += 1
-
-    print("=== SKILL spec validation ===")
-    print(f"Directory: {skill_dir}")
-    print()
-
-    # --- 1. SKILL.md existence ---
-    print("--- 1. File structure ---")
-    skill_file = os.path.join(skill_dir, "SKILL.md")
-    if os.path.isfile(skill_file):
-        check_pass("SKILL.md exists")
-    else:
-        check_fail("SKILL.md does not exist")
-        print("Cannot continue validation, SKILL.md is required")
-        sys.exit(1)
-
-    with open(skill_file, 'r', encoding='utf-8') as f:
-        content = f.read()
-    lines = content.splitlines()
-
-    # --- 2. Frontmatter ---
-    print()
-    print("--- 2. Frontmatter ---")
-
-    if lines and lines[0].strip() == '---':
-        check_pass("YAML frontmatter exists")
-    else:
-        check_fail("Missing YAML frontmatter (file should start with ---)")
-
-    # Extract name
-    name_match = re.search(r'^name:\s*(.+)$', content, re.MULTILINE)
-    name_field = name_match.group(1).strip() if name_match else ''
-
-    if name_field:
-        check_pass(f"name field exists: {name_field}")
-
-        if re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_field):
-            check_pass("name charset valid (lowercase letters/digits/hyphens only)")
-        else:
-            check_fail("name charset invalid: should only contain a-z/0-9/-, no leading/trailing or consecutive hyphens")
-
-        name_len = len(name_field)
-        if 1 <= name_len <= 64:
-            check_pass(f"name length valid ({name_len} chars)")
-        else:
-            check_fail(f"name length invalid: should be 1-64 chars (current {name_len})")
-
-        dir_name = os.path.basename(skill_dir.rstrip(os.sep))
-        if name_field == dir_name:
-            check_pass(f"name matches parent directory ({dir_name})")
-        else:
-            check_warn(f"name does not exactly match parent directory: name='{name_field}' vs dir='{dir_name}' (PascalCase dir convention exempted)")
-    else:
-        check_fail("name field is missing")
-
-    # Extract description
-    desc_match = re.search(r'^description:\s*(.+?)(?=\n[a-z]|\n---|\Z)', content, re.MULTILINE | re.DOTALL)
-    desc_field = desc_match.group(1).strip() if desc_match else ''
-
-    if desc_field:
-        desc_len = len(desc_field)
-        if desc_len <= 1024:
-            check_pass(f"description length valid ({desc_len} chars)")
-        else:
-            check_fail(f"description too long: should be <=1024 chars (current {desc_len})")
-    else:
-        check_fail("description field is missing or empty")
-
-    # Check license
-    if re.search(r'^license:', content, re.MULTILINE):
-        check_pass("license field exists")
-    else:
-        check_warn("license field missing (recommended)")
-        warnings += 1
-
-    # Check metadata
-    if re.search(r'^metadata:', content, re.MULTILINE):
-        check_pass("metadata field exists")
-    else:
-        check_warn("metadata field missing (recommended author/version)")
-        warnings += 1
-
-    # --- 3. Body ---
-    print()
-    print("--- 3. Body content ---")
-
-    # Count body lines (after frontmatter)
-    start = 0
-    end_idx = 0
-    for i, line in enumerate(lines):
-        if line.strip() == '---':
-            if start == 0:
-                start = i + 1
-            else:
-                end_idx = i + 1
-                break
-    if end_idx == 0:
-        end_idx = start
-    body_lines = lines[end_idx:]
-    body_count = len(body_lines)
-
-    if body_count <= 500:
-        check_pass(f"body line count valid ({body_count} lines, <=500)")
-    else:
-        check_warn(f"body line count high ({body_count} lines, recommended <500, consider splitting to references/)")
-        warnings += 1
-
-    # Check task parameters table
-    if re.search(r'(task param|param|\| .*param)', content, re.IGNORECASE) or 'param' in content.lower():
-        check_pass("contains task parameters table")
-    else:
-        check_warn("no task parameters table found (recommended)")
-        warnings += 1
-
-    # Check workflow
-    if re.search(r'(workflow|Phase)', content):
-        check_pass("contains workflow overview")
-    else:
-        check_warn("no workflow overview found (recommended)")
-        warnings += 1
-
-    # --- 4. Progressive disclosure ---
-    print()
-    print("--- 4. Progressive disclosure ---")
-
-    # Check references directory
-    refs_dir = os.path.join(skill_dir, "references")
-    if os.path.isdir(refs_dir):
-        ref_files = [f for f in os.listdir(refs_dir) if f.endswith('.md') and os.path.isfile(os.path.join(refs_dir, f))]
-        check_pass(f"references/ directory exists ({len(ref_files)} docs)")
-
-        # Check nesting depth (one level)
-        nested = False
-        for root, dirs, files in os.walk(refs_dir):
-            if root != refs_dir and dirs:
-                nested = True
-                break
-        if not nested:
-            check_pass("references maintain one-level depth")
-        else:
-            check_fail("references contains nested subdirectories, should maintain one-level depth")
-    else:
-        check_warn("no references/ directory (consider splitting detailed content here)")
-        warnings += 1
-
-    # Check assets directory
-    assets_dir = os.path.join(skill_dir, "assets")
-    if os.path.isdir(assets_dir):
-        asset_files = [f for f in os.listdir(assets_dir) if os.path.isfile(os.path.join(assets_dir, f))]
-        check_pass(f"assets/ directory exists ({len(asset_files)} files)")
-    else:
-        check_warn("no assets/ directory (add if templates/resources needed)")
-        warnings += 1
-
-    # Check scripts directory
-    scripts_dir = os.path.join(skill_dir, "scripts")
-    if os.path.isdir(scripts_dir):
-        script_files = [f for f in os.listdir(scripts_dir) if os.path.isfile(os.path.join(scripts_dir, f))]
-        check_pass(f"scripts/ directory exists ({len(script_files)} scripts)")
-    else:
-        check_warn("no scripts/ directory (add if executable scripts needed)")
-        warnings += 1
-
-    # Check relative paths (no absolute path references like ](/...)
-    abs_refs = re.findall(r'\]\(/[^)]+\)', content)
-    if len(abs_refs) == 0:
-        check_pass("file references use relative paths")
-    else:
-        check_fail(f"found {len(abs_refs)} absolute path references, should use relative paths")
-
-    # --- 5. Referenced file existence ---
-    print()
-    print("--- 5. Referenced file existence ---")
-
-    ref_paths = set(re.findall(r'\]\((references/[^)]+)\)', content))
-    asset_paths = set(re.findall(r'\]\((assets/[^)]+)\)', content))
-
-    for ref in sorted(ref_paths):
-        fullpath = os.path.join(skill_dir, ref)
-        if os.path.isfile(fullpath):
-            check_pass(f"referenced file exists: {ref}")
-        else:
-            check_fail(f"referenced file does not exist: {ref}")
-
-    for asset in sorted(asset_paths):
-        fullpath = os.path.join(skill_dir, asset)
-        if os.path.isfile(fullpath):
-            check_pass(f"referenced file exists: {asset}")
-        else:
-            check_fail(f"referenced file does not exist: {asset}")
-
-    # --- 6. Summary ---
-    print()
-    print("=== Validation summary ===")
-    print(f"  PASS: {passed}")
-    print(f"  FAIL: {failed}")
-    print(f"  WARN: {warnings}")
-    print()
-
-    if failed == 0:
-        print("ALL CHECKS PASSED")
-        sys.exit(0)
-    else:
-        print(f"VALIDATION FAILED: {failed} issue(s) must be fixed")
-        sys.exit(1)
-
-
-if __name__ == '__main__':
-    main()
+#!/usr/bin/env python3
+# @tool validate-skill
+# @description 校验SKILL目录是否符合Agent Skills规范，检查frontmatter、结构、渐进式披露
+# @param skillDir: string - SKILL目录绝对路径
+
+import sys
+import json
+import os
+import re
+
+
+def main():
+    # 解析参数：支持 JSON 字符串（MCP Gateway 调用）或直接命令行参数
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if arg.startswith('{'):
+            skill_dir = json.loads(arg).get('skillDir', '')
+        else:
+            skill_dir = arg
+    else:
+        print("Usage: validate-skill.py <skillDir>")
+        print("Error: skillDir parameter is required")
+        sys.exit(1)
+
+    if not skill_dir:
+        print("Usage: validate-skill.py <skillDir>")
+        print("Error: skillDir parameter is required")
+        sys.exit(1)
+
+    if not os.path.isdir(skill_dir):
+        print(f"Error: Directory does not exist: {skill_dir}")
+        sys.exit(1)
+
+    passed = 0
+    failed = 0
+    warnings = 0
+
+    def check_pass(msg):
+        nonlocal passed
+        print(f"  PASS  {msg}")
+        passed += 1
+
+    def check_fail(msg):
+        nonlocal failed
+        print(f"  FAIL  {msg}")
+        failed += 1
+
+    def check_warn(msg):
+        nonlocal warnings
+        print(f"  WARN  {msg}")
+        warnings += 1
+
+    print("=== SKILL spec validation ===")
+    print(f"Directory: {skill_dir}")
+    print()
+
+    # --- 1. SKILL.md existence ---
+    print("--- 1. File structure ---")
+    skill_file = os.path.join(skill_dir, "SKILL.md")
+    if os.path.isfile(skill_file):
+        check_pass("SKILL.md exists")
+    else:
+        check_fail("SKILL.md does not exist")
+        print("Cannot continue validation, SKILL.md is required")
+        sys.exit(1)
+
+    with open(skill_file, 'r', encoding='utf-8') as f:
+        content = f.read()
+    lines = content.splitlines()
+
+    # --- 2. Frontmatter ---
+    print()
+    print("--- 2. Frontmatter ---")
+
+    if lines and lines[0].strip() == '---':
+        check_pass("YAML frontmatter exists")
+    else:
+        check_fail("Missing YAML frontmatter (file should start with ---)")
+
+    # Extract name
+    name_match = re.search(r'^name:\s*(.+)$', content, re.MULTILINE)
+    name_field = name_match.group(1).strip() if name_match else ''
+
+    if name_field:
+        check_pass(f"name field exists: {name_field}")
+
+        if re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_field):
+            check_pass("name charset valid (lowercase letters/digits/hyphens only)")
+        else:
+            check_fail("name charset invalid: should only contain a-z/0-9/-, no leading/trailing or consecutive hyphens")
+
+        name_len = len(name_field)
+        if 1 <= name_len <= 64:
+            check_pass(f"name length valid ({name_len} chars)")
+        else:
+            check_fail(f"name length invalid: should be 1-64 chars (current {name_len})")
+
+        dir_name = os.path.basename(skill_dir.rstrip(os.sep))
+        if name_field == dir_name:
+            check_pass(f"name matches parent directory ({dir_name})")
+        else:
+            check_warn(f"name does not exactly match parent directory: name='{name_field}' vs dir='{dir_name}' (PascalCase dir convention exempted)")
+    else:
+        check_fail("name field is missing")
+
+    # Extract description
+    desc_match = re.search(r'^description:\s*(.+?)(?=\n[a-z]|\n---|\Z)', content, re.MULTILINE | re.DOTALL)
+    desc_field = desc_match.group(1).strip() if desc_match else ''
+
+    if desc_field:
+        desc_len = len(desc_field)
+        if desc_len <= 1024:
+            check_pass(f"description length valid ({desc_len} chars)")
+        else:
+            check_fail(f"description too long: should be <=1024 chars (current {desc_len})")
+    else:
+        check_fail("description field is missing or empty")
+
+    # Check license
+    if re.search(r'^license:', content, re.MULTILINE):
+        check_pass("license field exists")
+    else:
+        check_warn("license field missing (recommended)")
+        warnings += 1
+
+    # Check metadata
+    if re.search(r'^metadata:', content, re.MULTILINE):
+        check_pass("metadata field exists")
+    else:
+        check_warn("metadata field missing (recommended author/version)")
+        warnings += 1
+
+    # --- 3. Body ---
+    print()
+    print("--- 3. Body content ---")
+
+    # Count body lines (after frontmatter)
+    start = 0
+    end_idx = 0
+    for i, line in enumerate(lines):
+        if line.strip() == '---':
+            if start == 0:
+                start = i + 1
+            else:
+                end_idx = i + 1
+                break
+    if end_idx == 0:
+        end_idx = start
+    body_lines = lines[end_idx:]
+    body_count = len(body_lines)
+
+    if body_count <= 500:
+        check_pass(f"body line count valid ({body_count} lines, <=500)")
+    else:
+        check_warn(f"body line count high ({body_count} lines, recommended <500, consider splitting to references/)")
+        warnings += 1
+
+    # Check task parameters table
+    if re.search(r'(task param|param|\| .*param)', content, re.IGNORECASE) or 'param' in content.lower():
+        check_pass("contains task parameters table")
+    else:
+        check_warn("no task parameters table found (recommended)")
+        warnings += 1
+
+    # Check workflow
+    if re.search(r'(workflow|Phase)', content):
+        check_pass("contains workflow overview")
+    else:
+        check_warn("no workflow overview found (recommended)")
+        warnings += 1
+
+    # --- 4. Progressive disclosure ---
+    print()
+    print("--- 4. Progressive disclosure ---")
+
+    # Check references directory
+    refs_dir = os.path.join(skill_dir, "references")
+    if os.path.isdir(refs_dir):
+        ref_files = [f for f in os.listdir(refs_dir) if f.endswith('.md') and os.path.isfile(os.path.join(refs_dir, f))]
+        check_pass(f"references/ directory exists ({len(ref_files)} docs)")
+
+        # Check nesting depth (one level)
+        nested = False
+        for root, dirs, files in os.walk(refs_dir):
+            if root != refs_dir and dirs:
+                nested = True
+                break
+        if not nested:
+            check_pass("references maintain one-level depth")
+        else:
+            check_fail("references contains nested subdirectories, should maintain one-level depth")
+    else:
+        check_warn("no references/ directory (consider splitting detailed content here)")
+        warnings += 1
+
+    # Check assets directory
+    assets_dir = os.path.join(skill_dir, "assets")
+    if os.path.isdir(assets_dir):
+        asset_files = [f for f in os.listdir(assets_dir) if os.path.isfile(os.path.join(assets_dir, f))]
+        check_pass(f"assets/ directory exists ({len(asset_files)} files)")
+    else:
+        check_warn("no assets/ directory (add if templates/resources needed)")
+        warnings += 1
+
+    # Check scripts directory
+    scripts_dir = os.path.join(skill_dir, "scripts")
+    if os.path.isdir(scripts_dir):
+        script_files = [f for f in os.listdir(scripts_dir) if os.path.isfile(os.path.join(scripts_dir, f))]
+        check_pass(f"scripts/ directory exists ({len(script_files)} scripts)")
+    else:
+        check_warn("no scripts/ directory (add if executable scripts needed)")
+        warnings += 1
+
+    # Check relative paths (no absolute path references like ](/...)
+    abs_refs = re.findall(r'\]\(/[^)]+\)', content)
+    if len(abs_refs) == 0:
+        check_pass("file references use relative paths")
+    else:
+        check_fail(f"found {len(abs_refs)} absolute path references, should use relative paths")
+
+    # --- 5. Referenced file existence ---
+    print()
+    print("--- 5. Referenced file existence ---")
+
+    ref_paths = set(re.findall(r'\]\((references/[^)]+)\)', content))
+    asset_paths = set(re.findall(r'\]\((assets/[^)]+)\)', content))
+
+    for ref in sorted(ref_paths):
+        fullpath = os.path.join(skill_dir, ref)
+        if os.path.isfile(fullpath):
+            check_pass(f"referenced file exists: {ref}")
+        else:
+            check_fail(f"referenced file does not exist: {ref}")
+
+    for asset in sorted(asset_paths):
+        fullpath = os.path.join(skill_dir, asset)
+        if os.path.isfile(fullpath):
+            check_pass(f"referenced file exists: {asset}")
+        else:
+            check_fail(f"referenced file does not exist: {asset}")
+
+    # --- 6. Summary ---
+    print()
+    print("=== Validation summary ===")
+    print(f"  PASS: {passed}")
+    print(f"  FAIL: {failed}")
+    print(f"  WARN: {warnings}")
+    print()
+
+    if failed == 0:
+        print("ALL CHECKS PASSED")
+        sys.exit(0)
+    else:
+        print(f"VALIDATION FAILED: {failed} issue(s) must be fixed")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()