@buaa_smat/hometrans 0.1.6 → 0.1.7

package/README.md

@@ -13,13 +13,111 @@ npm install -g @buaa_smat/hometrans
 ht init
 ```
 
-One-shot via `npx` (no global install required):
+Requires Node.js **>= 18**.
+
+---
+
+## Setup Guide
+
+After running `ht init`, follow these steps to complete the installation:
+
+### Step 1: Choose your target editor
+
+`ht init` automatically detects supported editors (Claude Code, Cursor, OpenCode, Codex) and presents an interactive selection prompt. Use **Space** to toggle and **Enter** to confirm.
+
+![Choose target editor](resource/choose_editor.png)
+
+### Step 2: Finish initialization
+
+After confirming your editor selection, HomeTrans installs all bundled **skills**, **agents**, and the **MCP server** into each selected editor's configuration directory. The installation is idempotent — re-running `ht init` overwrites only bundled content.
+
+![Finish initialization](resource/finish_init.png)
+
+> **Tip:** Run `ht init --all` to skip the editor prompt and install to every detected editor automatically.
+
+---
+
+## HarmonyOS Migration Guide
+
+鸿蒙软件迁移指导，提供完整的 Android 到 HarmonyOS 迁移流程：
+
+### Step 1: Resource Conversion (资源转换)
+
+> `hmos-batch-ui-align` 内部会自动调用资源转换；如果是批量UI迁移场景则可跳过此步骤。
+
+将 Android 资源文件（图片、字符串、颜色、尺寸等）转换为 HarmonyOS 格式。
 
-```bash
-npx hometrans init
+```
+/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
 ```
 
-Requires Node.js **>= 18**.
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `android-project-path` | **必选** | Android 项目根目录路径（含 `build.gradle` 或 `build.gradle.kts`） |
+| `harmonyos-project-path` | **必选** | HarmonyOS 项目输出路径 |
+| `resource_mapping_path` | **必选** | Android ↔ HarmonyOS 资源映射文档的完整输出路径（`.md`） |
+| `apk-path` | 可选 | Android APK 文件路径；提供后跳过 Gradle 构建和 apktool 解包步骤，直接从 APK 提取资源 |
+
+### Step 2: UI Migration (UI迁移)
+
+运行以下命令之一完成 Android UI 的全量或增量迁移。
+
+#### 全量迁移 — `hmos-batch-ui-align`
+
+```
+/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `android_project_dir` | **必选** | Android 项目根目录路径 |
+| `harmony_project_dir` | **必选** | HarmonyOS 项目输出路径 |
+| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录路径（每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`）；不提供时 skill 自动通过 ADB 抓取 |
+| `pages` | 可选 | 显式列出的页面子集（如不提供则处理所有页面） |
+
+#### 增量迁移 — `hmos-incremental-ui-align`
+
+项目路径通过 `config.json` 文件配置（参考 skill 目录下的 `config-example.json`），对齐目标在消息中描述（如 "帮我对齐设置页面的关于页面"）。
+
+```
+/hmos-incremental-ui-align config-path=<config.json路径>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `config-path` | **必选** | `config.json` 文件路径，包含 `android.project_dir`, `harmony.project_dir`, `hmos_sdk_dir`, `glm_api_key`, `capture_output_dir` 等字段 |
+
+### Step 3: Generate Spec (生成需求规格)
+
+运行 `hmos-spec-generate` 从原始需求描述 `.txt` 文件生成原子场景需求规格文档。
+
+```
+/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `requirement-description-file` | **必选** | 需求描述 `.txt` 文件路径（每段以 `REQ` 开头，空行分隔） |
+| `android-project-path` | **必选** | Android 项目根目录路径（必须位于 Git 仓库内） |
+| `spec-output-dir` | **必选** | 规格文档输出目录（自动创建；每个 REQ 生成 `<feature>-SPEC.md` + `.trace/<feature>.md`） |
+
+### Step 4: Convert Pipeline (逻辑代码开发)
+
+运行 `hmos-convert-pipeline` 完成后续的逻辑代码开发、代码检视、集成测试流程。
+
+```
+/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> assets-output-path=<输出报告目录>
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `android-project-path` | **必选** | Android 项目根目录路径 |
+| `harmonyos-project-path` | **必选** | HarmonyOS 项目根目录路径 |
+| `assets-output-path` | **必选** | 输出/报告文件的存放目录（需包含 `plan.md` 需求规格文件） |
+| `max-rounds-review` | 可选 | 代码检视循环最大轮数（正整数 `>= 1`，默认 `2`） |
+| `max-rounds-test` | 可选 | 自测循环最大轮数（正整数 `>= 1`，默认 `2`） |
+| `variant` | 可选 | `enhanced`（默认，全功能 agent）或 `baseline`（纯 LLM baseline agent） |
+| `skip-test` | 可选 | `true` 跳过集成测试阶段（无真机验证环境时需要设置为true，默认 `false`） |
 
 ---
 
@@ -66,55 +164,16 @@ Requires Node.js **>= 18**.
 
 ---
 
-## What `ht mcp` does
-
-Starts a stdio-mode MCP server exposing the following tool:
-
-### `extract_commit_context`
-
-Extracts code context index from a given git commit in a HarmonyOS project (git diff + ArkTS semantic dependency analysis), for use during AI-assisted Android-to-HarmonyOS code review.
-
-**Input parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `projectPath` | string | Yes | Absolute path to HarmonyOS project root (must contain `.git`) |
-| `commitId` | string | Yes | Git commit ID (diffs against its first parent) |
-| `mode` | string | No | `"default"` builds full call graph; other values skip (default: `"default"`) |
-| `ohosSdkPath` | string | No | OpenHarmony SDK ETS path; falls back to env var `OHOS_SDK_PATH` |
-| `hmsSdkPath` | string | No | HMS SDK ETS path; falls back to env var `HMS_SDK_PATH` |
-
-**Output:** `{path, kind, ranges?, resourceNames?}[]`
-- `source` files: 1-based `[start, end]` line-range arrays
-- `resource` files: list of referenced resource names
-
----
-
 ## Skills
 
-| Skill | Trigger phrases | Description |
-|-------|-----------------|-------------|
-| `hmos-convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "hmos-convert-pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 9 stages: Logic Context → Logic Coding → Build → Code Review → Review Fix → Rebuild → Self-Test → Self-Test Fix → Rebuild |
-| `hmos-spec-generate` | "spec generation", "generate spec", "requirement to spec", "atomic scenarios", "scenario decomposition", "req to spec" | Generates atomic-scenario requirement specs from raw `.txt` requirement batches. Reads REQ blocks, explores the Android code graph via GitNexus, writes per-REQ trace files, then synthesizes specs from the trace |
-| `hmos-resources-convert` | "Android resources to HarmonyOS", "migrate Android res", "convert drawables/strings/colors" | Converts Android project resources (strings, colors, dimensions, images, drawables, icons) into HarmonyOS resources, including qualifier directories and XML→JSON format conversion |
-| `hmos-incremental-ui-align` | "UI对齐", "页面对齐", "和安卓对齐", "鸿蒙页面修复", "UI增量开发", "align HarmonyOS with Android" | Automated HarmonyOS-Android UI alignment: navigates to target pages on both devices, captures view trees + screenshots, then aligns HarmonyOS code to match Android |
-| `hmos-batch-ui-align` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) pages |
-| `hmos-integration-test` | "跑自测", "运行自测", "自动测试", "设备测试", "self test", "run autotest" | Runs on-device self-test for a HarmonyOS app: parses `test_case.md`, installs the HAP, executes AutoTest, and produces a verification report — optionally entering a test-and-fix loop |
-
-### `hmos-convert-pipeline` Arguments
-
-1. `android-project-path` (required): path to the Android source project
-2. `harmonyos-project-path` (required): path to the target HarmonyOS project
-3. `assets-output-path` (required): directory for output/report files
-4. `max-rounds-review` (optional, default `2`): max Code Review → Fix loop rounds
-5. `max-rounds-test` (optional, default `2`): max Self-Test → Fix loop rounds
-6. `variant` (optional, default `enhanced`): `enhanced` | `baseline` — selects the Stage 1/1a agent family
-
-### `hmos-spec-generate` Arguments
-
-1. `requirement-description-file` (required): absolute path to a single `.txt` file containing one or more REQ blocks separated by blank lines
-2. `android-project-path` (required): absolute path to the Android project root (must be inside a Git repo)
-3. `spec-output-dir` (required): absolute path to the directory where spec files will be written
+| Skill | Trigger phrases | Description | Prerequisites | Arguments | Example |
+|-------|-----------------|-------------|---------------|-----------|--------|
+| `hmos-convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "hmos-convert-pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 4 stages: Logic Development (Context Builder) → Logic Coding → Build → Code Review/Fix/Rebuild loop → Self-Test/Fix/Rebuild loop | `assets-output-path` 下需存在 `plan.md` 需求规格文件 | `android-project-path` (required), `harmonyos-project-path` (required), `assets-output-path` (required), `max-rounds-review` (optional, default 2), `max-rounds-test` (optional, default 2), `variant` (optional, default enhanced), `skip-test` (optional, default false) | `"/hmos-convert-pipeline android-project-path=D:/path/to/android harmonyos-project-path=D:/path/to/harmonyos assets-output-path=D:/path/to/output"` |
+| `hmos-spec-generate` | "spec generation", "generate spec", "requirement to spec", "atomic scenarios", "scenario decomposition", "req to spec" | Generates atomic-scenario requirement specs from raw `.txt` requirement batches. Reads REQ blocks, explores the Android code graph via GitNexus, writes per-REQ trace files, then synthesizes specs from the trace | 需求描述文件 (`.txt`)，每段以 `REQ` 开头 | `requirement-description-file` (required), `android-project-path` (required), `spec-output-dir` (required) | `"/hmos-spec-generate requirement-description-file=D:/path/to/req.txt android-project-path=D:/path/to/android spec-output-dir=D:/path/to/specs"` |
+| `hmos-resources-convert` | "Android resources to HarmonyOS", "migrate Android res", "convert drawables/strings/colors" | Converts Android project resources (strings, colors, dimensions, images, drawables, icons) into HarmonyOS resources, including qualifier directories and XML→JSON format conversion | Android 项目中需包含 `res/` 资源目录 | `android-project-path` (required), `harmonyos-project-path` (required), `resource_mapping_path` (required), `apk-path` (optional) | `"/hmos-resources-convert android-project-path=D:/path/to/android harmonyos-project-path=D:/path/to/harmonyos resource_mapping_path=D:/path/to/resource_mapping.md"` |
+| `hmos-incremental-ui-align` | "UI对齐", "页面对齐", "和安卓对齐", "鸿蒙页面修复", "UI增量开发", "align HarmonyOS with Android" | Automated HarmonyOS-Android UI alignment: navigates to target pages on both devices, captures view trees + screenshots, then aligns HarmonyOS code to match Android | 需连接 Android 设备进行 UI 对比；`config-path` 指向的 `config.json` 中需配置项目路径、SDK 路径、API key | `config-path` (required) | `"/hmos-incremental-ui-align config-path=D:/path/to/config.json 帮我对齐设置页面的关于页面"` |
+| `hmos-batch-ui-align` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) pages | `ui_info_root` 下需包含 `page_NNNN_ActivityName` 格式的页面快照子目录 | `android_project_dir` (required), `harmony_project_dir` (required), `ui_info_root` (optional), `pages` (optional) | `"/hmos-batch-ui-align android_project_dir=D:/path/to/android harmony_project_dir=D:/path/to/harmonyos ui_info_root=D:/path/to/pages"` |
+| `hmos-integration-test` | "跑自测", "运行自测", "自动测试", "设备测试", "self test", "run autotest" | Runs on-device self-test for a HarmonyOS app: parses `test_case.md`, installs the HAP, executes AutoTest, and produces a verification report — optionally entering a test-and-fix loop | 需存在 `test_case.md` 测试用例文件，设备需安装待测 HAP | `test-case-path` (required), `hap-path` (required), `output-path` (optional), `pre-test-case-path` (optional), `android-project-path` (optional), `max-rounds` (optional, default 3) | `"/hmos-integration-test test-case-path=D:/path/to/test_case.md hap-path=D:/path/to/app-signed.hap"` |
 
 ---
 
@@ -125,14 +184,15 @@ Extracts code context index from a given git commit in a HarmonyOS project (git
 | `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
 | `logic-coder` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
 | `build-fixer` | Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until the build succeeds |
-| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage || `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
+| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage |
+| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
 | `spec-generator` | Generates requirement spec documents for each requirement description file in a folder by exploring the Android codebase and decomposing into atomic user scenarios |
 | `self-tester` | Unified self-test agent — parses `test_case.md` into `testcases.json`, runs on-device AutoTest verification, and produces a report. A `setup` boolean controls whether the parse phase runs (skip on round-2+ to reuse prior artifacts) |
 | `self-test-fixer` | Fixes issues identified by self-testing — reads the self-test report, white-box verifies failures, plans and executes fixes in order |
 
 ---
 
-MIT
+
 
 <p align="center">
 <a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buaa_smat/hometrans",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "HomeTrans (Android-to-HarmonyOS) skill + agent installer. Run `ht init` to distribute conversion skills and subagents into AI editors.",
   "license": "MIT",
   "type": "module",

package/skills/hmos-incremental-ui-align/SKILL.md

@@ -17,23 +17,25 @@ You are writing ArkTS codes.
 - 不要做和用户需求无关的其他修改
 - 
 ## Step 0: Load Config
-The user MUST specify the path to a `config.json` file when invoking this skill (e.g., as part of the request: "config: D:\path\to\config.json"). Read that file from the user-provided path. If the user did not provide a path, ask them for it before proceeding. See `config-example.json` in this skill's directory for the expected schema.
-
-The config provides all fixed paths so the user only describes what needs to be aligned.
-Key config fields:
-- `android.app_name`, `android.package` — Android app info for navigation
-- `android.project_dir` — Android source code root
-- `harmony.app_name`, `harmony.package` — HarmonyOS app info for navigation
-- `harmony.project_dir` — HarmonyOS project root
-- `hmos_sdk_dir` — HarmonyOS SDK path for API reference
-- `glm_api_key` — Zhipu GLM API key for phone-agent
-- `capture_output_dir` — base directory for captured page data
-- `navigation_tool` = `scripts/app_feature_verify.py`                                                                                   
-- `capture_tool` = `scripts/page_capture.py`
+The user MUST provide a `config-path` when invoking this skill (e.g., `config-path: D:\path\to\config.json`). The config file must exist before running — verify with a Read, and if it's missing or unreadable, ask the user for a valid path. Refer to `config-example.json` in this skill's directory for the expected schema.
+
+Config fields:
+
+| Field | Description |
+|---|---|
+| `android.app_name` | Android app name for navigation |
+| `android.package` | Android app package name |
+| `android.project_dir` | Android source code root path |
+| `harmony.app_name` | HarmonyOS app name for navigation |
+| `harmony.package` | HarmonyOS app package name |
+| `harmony.project_dir` | HarmonyOS project root path |
+| `hmos_sdk_dir` | HarmonyOS SDK path (ETS API reference) |
+| `glm_api_key` | Zhipu GLM API key for phone-agent |
+| `capture_output_dir` | Base directory for captured page data |
 
 ## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
 
-Read `scripts/navigation-capure.md` to learn the usage of `navigation_tool` and `capture_tool`.
+Read `scripts/navigation-capure.md` to learn the usage of `scripts/app_feature_verify.py` (navigation) and `scripts/page_capture.py` (capture).
 
 ### Step 1.1: Parse User Request and Build Capture Plan
 Analyze the user's description and build a list of **base pages** to capture.
@@ -48,8 +50,8 @@ Create the timestamped output directory and per-page sub-directories following t
 
 ### Step 1.2: Capture Base Pages
 For each base page in the plan, on **both** Android and HarmonyOS devices:
-1. Use `navigation_tool` to navigate to the page.
-2. On success, use `capture_tool` to capture the view tree and screenshot.
+1. Use `scripts/app_feature_verify.py` to navigate to the page.
+2. On success, use `scripts/page_capture.py` to capture the view tree and screenshot.
 3. For HarmonyOS pages that don't exist yet, navigation will fail — leave the directory empty (expected).
 
 ### Step 1.3: Discover and Capture Interactive States
@@ -61,7 +63,7 @@ After capturing each base page, scan its view tree for **interactive elements th
 
 **For each interactive element found:**
 1. Create a separate capture directory: `{platform}_page_{i}_{base_name}_{state_type}_{state_name}` (e.g., `android_page_1_detail_tab_city`, `android_page_1_detail_popup_filter_identity`).
-2. Navigate to the base page (reuse the same nav path), then append the click action to trigger the state change. Capture with `capture_tool`.
+2. Navigate to the base page (reuse the same nav path), then append the click action to trigger the state change. Capture with `scripts/page_capture.py`.
 3. Repeat for **both** Android and HarmonyOS devices.
 4. Each captured state is treated as a separate page pair in Step 2 and Step 3.
 

package/skills/skill-quality-evaluator/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: skill-quality-evaluator
+description: Evaluate the quality of an Agent Skill across multiple dimensions — specification compliance, progressive disclosure, content efficiency, instruction quality, description effectiveness, script quality, and evaluability. Use this skill when the user wants to assess, review, score, or audit a skill, check if a skill follows best practices, get a quality report for a skill, or understand what improvements a skill needs. Triggers on phrases like "evaluate this skill", "review my skill", "skill quality check", "audit SKILL.md", "how good is this skill", "assess skill quality", "评分", "评估skill", "检查skill质量".
+---
+
+# Skill Quality Evaluator
+
+Evaluate a target skill across 7 dimensions, each broken into concrete sub-criteria. The goal is a structured, evidence-based assessment — not a vibe check.
+
+## Foundational References
+
+This skill's evaluation criteria are derived from five authoritative documents bundled in `references/`. Load them when you need deeper context on *why* a criterion matters — especially when the target skill has a borderline score and you need to cite the official guidance.
+
+| Document | Covers | Most Relevant To |
+|----------|--------|------------------|
+| `references/Specification.md` | Complete Agent Skills format spec: frontmatter fields, naming rules, directory structure, progressive disclosure design | Dimensions 1, 2 |
+| `references/Best-practices-for-skill-creators.md` | How to write well-scoped, calibrated, effective skill instructions — start from real expertise, spend context wisely, calibrate control, patterns (gotchas, templates, checklists, validation loops, plan-validate-execute) | Dimensions 3, 4 |
+| `references/Evaluating-skill-output-quality.md` | Test case design, assertions, grading, benchmarking, human review, the iteration loop | Dimension 7 |
+| `references/Optimizing-skill-descriptions.md` | How the `description` field drives skill triggering, how to write effective descriptions, trigger eval design, train/validation splits, the optimization loop | Dimension 5 |
+| `references/Using-scripts-in-skills.md` | One-off commands, self-contained scripts, designing scripts for agentic use (non-interactive, --help, error messages, structured output) | Dimension 6 |
+
+The 7-dimension framework below is a synthesis of all five documents. If a criterion feels unclear, open the corresponding document — it contains the rationale and examples.
+
+## Bundled Resources
+
+This skill also includes two reference files and one asset. Load them at the specified points — do not load everything upfront.
+
+| File | When to Load | What It Contains |
+|------|-------------|------------------|
+| `references/scoring-rubric.md` | **Before assigning scores** (after reading the target skill and collecting evidence) | 1-5 scale anchors for every sub-criterion, dimension weight table, and overall score interpretation ranges. Use these anchors to map evidence to scores — never score without consulting this file. |
+| `references/report-template.md` | **After all scores are finalized** (when writing the final report) | Exact Markdown template for the output report. Follow its structure precisely so every report is consistent and machine-readable. |
+| `assets/SKILL_TEMPLATE.md` | **When the user asks to create a new skill** or wants to see what a well-structured skill looks like, or when the evaluation report recommends a structural rewrite | A SKILL.md template with standard frontmatter plus three extra sections: Input Parameters table, Output Content table, and Preconditions (with failure handling patterns). Use this as the starting point for generating new skills. |
+
+## Workflow
+
+1. Confirm the skill path from the user. If the user only gave a skill name, search under `./skills/` and `~/.claude/` for it.
+2. Read the target skill's `SKILL.md` fully. Note its directory structure — check for `scripts/`, `references/`, `assets/`, `evals/`.
+3. Read the 7 dimension checklists below to know what evidence to collect. Scan the target skill's auxiliary files (`scripts/`, `references/`, `evals/`) if they exist.
+4. **Load `references/scoring-rubric.md`**, then assign a 1-5 score per sub-criterion using the scale anchors.
+5. Compute dimension averages and the overall weighted score.
+6. **Load `references/report-template.md`** and write the final report following that exact template.
+
+## Dimension 1 — Specification Compliance
+
+Check the `SKILL.md` frontmatter and directory against the Agent Skills spec.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 1.1 | Frontmatter validity | YAML parses without errors; `name` and `description` are present |
+| 1.2 | Name rules | 1-64 chars, lowercase alphanumeric + hyphens only, no leading/trailing hyphen, no consecutive hyphens, matches parent directory name |
+| 1.3 | Description length | 1-1024 characters |
+| 1.4 | Directory structure | `SKILL.md` exists at root; optional dirs (`scripts/`, `references/`, `assets/`) used appropriately |
+| 1.5 | No broken references | Every file path mentioned in SKILL.md (`references/*.md`, `scripts/*`, `assets/*`) resolves to an existing file. Every reference/script/asset listed in the skill's own resource tables exists on disk. No 404s. |
+
+## Dimension 2 — Progressive Disclosure
+
+Assess whether the skill respects context budgets and loads detail on demand.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 2.1 | SKILL.md size | Under 500 lines; core instructions only |
+| 2.2 | Reference usage | Detailed/exhaustive material moved to `references/` instead of inline; reference files are focused and reasonably sized |
+| 2.3 | Load triggers | When referencing auxiliary files, the skill tells the agent *when* to load them (e.g., "if the API returns 4xx, read `references/errors.md`"), not just "see references/" |
+| 2.4 | Path conventions | File references use relative paths from skill root; no deeply nested reference chains (one level deep from SKILL.md) |
+
+## Dimension 3 — Content Efficiency
+
+Evaluate whether every token earns its place.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 3.1 | No generic filler | Does NOT explain concepts the agent already knows (e.g., what a PDF is, how HTTP works). Focuses on what the agent would get wrong without the skill. |
+| 3.2 | Coherent scope | The skill encapsulates one coherent unit of work. Not so narrow that multiple skills must chain for basic tasks; not so broad that it's hard to activate precisely. |
+| 3.3 | Appropriate detail | Not an exhaustive reference manual, not a vague one-liner. Enough structure to guide without over-constraining. |
+| 3.4 | Domain grounding | Contains project-specific, domain-specific, or environment-specific knowledge — not just general best practices the agent already knows. |
+
+## Dimension 4 — Instruction Quality
+
+Assess how well the skill *teaches the agent to approach* the task.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 4.1 | Calibrated specificity | Flexible where approaches vary, prescriptive where operations are fragile. Not uniformly rigid or uniformly loose. |
+| 4.2 | Defaults over menus | When multiple tools/approaches work, picks a clear default with brief mention of alternatives — doesn't present an undifferentiated list of options. |
+| 4.3 | Procedural over declarative | Teaches *how to approach* a class of problems, not *what to produce* for a specific instance. The method generalizes. |
+| 4.4 | Explains why | Instructions include reasoning where non-obvious ("because X tends to Y"). Not just naked directives. |
+| 4.5 | Gotchas | Captures environment-specific corrections — things that defy reasonable assumptions and would cause errors if not stated. |
+
+## Dimension 5 — Description Effectiveness
+
+Evaluate the `description` frontmatter field as a triggering mechanism.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 5.1 | Imperative framing | Uses "Use this skill when..." or equivalent instructional framing, not passive "This skill does..." |
+| 5.2 | Intent-focused | Describes what the user is trying to achieve, not the skill's internal mechanics. |
+| 5.3 | Trigger coverage | Lists specific contexts and trigger phrases. Pushy enough — includes cases where the user doesn't name the domain explicitly. |
+| 5.4 | Conciseness | Long enough to cover scope, short enough not to bloat context. Under the 1024-char hard limit. |
+| 5.5 | Keyword specificity | Contains concrete keywords that disambiguate from adjacent skills. Would match relevant prompts and not match irrelevant ones. |
+
+## Dimension 6 — Script Quality
+
+Skip this dimension entirely if the skill has no `scripts/` directory. Otherwise:
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 6.1 | Self-contained | Dependencies declared inline (PEP 723, package.json, bundler/inline) or clearly documented. |
+| 6.2 | Non-interactive | No TTY prompts, password dialogs, or confirmation menus. All input via flags/env/stdin. |
+| 6.3 | Help output | `--help` shows usage, flags, and examples. |
+| 6.4 | Error messages | Say what went wrong, what was expected, and what to try. Not opaque. |
+| 6.5 | Structured output | Prefers JSON/CSV/TSV over free-form text for data; separates diagnostics to stderr. |
+
+## Dimension 7 — Evaluability
+
+Check whether the skill can be systematically tested and improved.
+
+| # | Criterion | What to Check |
+|---|-----------|---------------|
+| 7.1 | Test cases exist | Has `evals/evals.json` with at least 2 test cases. |
+| 7.2 | Realistic prompts | Test prompts look like real user messages — file paths, personal context, varied formality. Not generic "do X". |
+| 7.3 | Verifiable assertions | Assertions are specific, objective, and programmatically checkable where possible. Not vague ("output is good"). |
+| 7.4 | Edge case coverage | At least one test covers a boundary condition or ambiguous input. |
+
+## Scoring
+
+Each sub-criterion scores 1-5. The full scale anchors, dimension weights, and score interpretation ranges are in `references/scoring-rubric.md` — you should have already loaded it per the workflow above. After scoring:
+
+1. Compute dimension averages (mean of sub-criteria scores in each dimension).
+2. Compute the overall weighted score using the weights table in `references/scoring-rubric.md`. Redistribute N/A dimension weights proportionally.
+3. Identify the top 3 strengths (highest-scoring sub-criteria with most impact) and top 3 improvement areas (lowest-scoring, highest-weight items first).
+4. Write the final report following the template in `references/report-template.md` (loaded per the workflow above).
+
+## Important Notes
+
+- **Evidence is mandatory.** Every score must cite a specific line, pattern, or absence in the skill files. No "feels like a 4."
+- **Missing dimensions.** If a dimension is not applicable (e.g., no scripts), mark it N/A and exclude from the overall score.
+- **Be constructive.** The goal is to help the skill author improve, not to judge. Frame weaknesses as specific, actionable changes.
+- **Read the whole skill.** Scan `scripts/`, `references/`, and `evals/` if they exist — don't judge on SKILL.md alone.

package/skills/skill-quality-evaluator/assets/SKILL_TEMPLATE.md

@@ -0,0 +1,77 @@
+---
+name: <skill-name>
+description: >
+  <what it does + when to use it. Use imperative framing, focus on user intent.
+  List trigger phrases. Keep under 1024 chars.>
+license: <license-name or bundled license file>
+compatibility: <environment requirements — product, system packages, network, etc.>
+allowed-tools: 
+---
+
+# <Skill Title> — <One-line summary>
+
+<Brief overview of what this skill accomplishes — 2-3 sentences.>
+
+## Input Parameters
+<!--
+  List every input the skill expects from the user. Use this exact table format.
+  Mark optional params with "(optional)" in the Variable column.
+-->
+
+| Variable | Required | Meaning | Typical User Phrases / Expected Format |
+|----------|----------|---------|----------------------------------------|
+| `<param1>` | Yes | <what this parameter represents> | <examples of how users describe it, expected format, fallback sources> |
+| `<param2>` | Yes | <what this parameter represents> | <examples of how users describe it, expected format, fallback sources> |
+| `<param3>` | No | <what this parameter represents> | <examples, format, default value if omitted> |
+
+<!-- Extraction rule: if a required param is missing, ask the user — do NOT guess. -->
+
+## Output Content
+<!--
+  List every artifact or result this skill produces. Be specific about formats,
+  locations, and what a successful result looks like.
+-->
+
+| Output | Type | Location / Path | Description |
+|--------|------|-----------------|-------------|
+| `<output1>` | <file \| directory \| in-message> | `<where it goes>` | <what it contains, format> |
+| `<output2>` | <file \| directory \| in-message> | `<where it goes>` | <what it contains, format> |
+
+## Preconditions
+<!--
+  Every file, directory, tool, or environment state the skill assumes exists
+  BEFORE it starts. For each precondition, define the check AND the fallback.
+-->
+
+| # | Precondition | How to Verify | On Failure |
+|---|-------------|---------------|------------|
+| 1 | `<expected state>` | `<bash command or file check to run>` | `<what to tell the user / what to do — e.g., "ask the user to provide X", "create it automatically by running Y", "abort and tell the user to install Z">` |
+
+<!--
+  Failure handling patterns (pick the right one for each precondition):
+  - **Ask user**: "Parameter X is missing — please provide ..."
+  - **Auto-create**: "Run scripts/setup.sh to generate ..."
+  - **Auto-install**: "pip install X" / "npm install X"
+  - **Abort**: "Cannot proceed — X requires Y. Please ... then retry."
+-->
+
+---
+
+## Workflow
+<!--
+  PATTERN A: Progress Checklist
+  - [ ] markers let the agent track what's done and what remains.
+  - After each step: validate the output before checking the box.
+  - Include the tool/command inside each step so the agent knows what to run.
+  - Steps with (depends: Step N) must wait — the agent skips them until the
+    prerequisite step is checked.
+-->
+
+Progress:
+- [ ] **Step 1:** <action verb + object> — run `scripts/<name>.py <args>`
+- [ ] **Step 2:** <action verb + object> — <tool or command> (depends: Step 1)
+- [ ] **Step 3:** <action verb + object> — <tool or command> (depends: Step 2)
+- [ ] **Step 4:** Validate — run `scripts/<validate>.py <args>`
+- [ ] **Step 5:** Verify output — <final check>
+
+---