docs(packaging): professionalize packages index and link it in README

script/package_skills.py

@@ -130,7 +130,6 @@ def validate_bundle_contains_skills(bundle_path: Path, source_dir_names: list[st
 
 def build_index(
     output_file: Path,
-    skills_root: Path,
     valid_skills: list[SkillRecord],
     skipped: list[str],
     warnings: list[str],
@@ -140,22 +139,40 @@ def build_index(
     def table_safe(value: str) -> str:
         return value.replace("|", r"\|").replace("\n", " ").strip()
 
+    def concise_scope(value: str, max_len: int = 120) -> str:
+        cleaned = " ".join(value.split()).strip()
+        if not cleaned:
+            return "N/A"
+
+        parts = cleaned.split(". ", 1)
+        scope = parts[0].strip()
+        if len(parts) > 1 and not scope.endswith("."):
+            scope = f"{scope}."
+
+        if len(scope) > max_len:
+            scope = scope[: max_len - 3].rstrip() + "..."
+
+        return table_safe(scope)
+
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
     all_ok = all(ok for ok, _ in validations)
+    passed_validations = sum(1 for ok, _ in validations if ok)
+    total_validations = len(validations)
     package_dir = output_file.parent
     upload_md_dir = package_dir / "upload-md"
 
     lines = [
-        "# Packages Index",
+        "# Mechanical Skills Packages Index",
         "",
         "## Snapshot",
         "",
-        f"- Generated (UTC): **{ts}**",
-        f"- Skills root: `{skills_root}`",
-        f"- Valid skills packaged: **{len(valid_skills)}**",
-        "- Per-skill formats: `.skill` and `.zip` in separate folders",
-        f"- Bundle: [`{bundle_path.name}`](bundles/{bundle_path.name})",
-        f"- Validation status: **{'PASS' if all_ok else 'FAIL'}**",
+        "| Item | Value |",
+        "| --- | --- |",
+        f"| Generated (UTC) | `{ts}` |",
+        f"| Valid skills packaged | **{len(valid_skills)}** |",
+        "| Per-skill formats | `.skill` and `.zip` (separate folders) |",
+        f"| Bundle | [`{bundle_path.name}`](bundles/{bundle_path.name}) |",
+        f"| Validation status | **{'PASS' if all_ok else 'FAIL'}** ({passed_validations}/{total_validations}) |",
         "",
         "## Quick Links",
         "",
@@ -168,8 +185,8 @@ def build_index(
         "",
         "## Skill Catalog",
         "",
-        "| Skill | Description | Source | Markdown | .skill | .zip |",
-        "| --- | --- | --- | --- | --- | --- |",
+        "| Skill | Scope | Source | Packages | Markdown |",
+        "| --- | --- | --- | --- | --- |",
     ]
 
     for skill in sorted(valid_skills, key=lambda item: item.package_name):
@@ -185,14 +202,14 @@ def build_index(
         )
         source_cell = (
             f"[`{skill.source_dir_name}/SKILL.md`]({source_rel})"
-            if Path(skills_root / skill.source_dir_name / "SKILL.md").exists()
+            if (skill.source_path / "SKILL.md").exists()
             else "N/A"
         )
 
         lines.append(
-            "| `{name}` | {description} | {source} | {markdown} | [`{name}.skill`]({skill_pkg}) | [`{name}.zip`]({zip_pkg}) |".format(
+            "| `{name}` | {scope} | {source} | [`.skill`]({skill_pkg}) / [`.zip`]({zip_pkg}) | {markdown} |".format(
                 name=skill.package_name,
-                description=table_safe(skill.description),
+                scope=concise_scope(skill.description),
                 source=source_cell,
                 markdown=markdown_cell,
                 skill_pkg=skill_rel,
@@ -200,7 +217,7 @@ def build_index(
             )
         )
 
-    lines.extend(["", "## Validation"])
+    lines.extend(["", "## Validation Checks"])
     lines.extend(
         [f"- [{'x' if ok else ' '}] {message}" for ok, message in validations]
     )
@@ -314,7 +331,6 @@ def package_skills(skills_root: Path, output_dir: Path, bundle_name: str, spot_c
     index_path = output_dir / "PACKAGES_INDEX.md"
     build_index(
         output_file=index_path,
-        skills_root=skills_root,
         valid_skills=valid_skills,
         skipped=skipped,
         warnings=warnings,