feat(packaging): improve packages index with professional linked catalog

script/package_skills.py

@@ -130,30 +130,72 @@ def build_index(
     validations: list[tuple[bool, str]],
     bundle_path: Path,
 ) -> None:
+    def table_safe(value: str) -> str:
+        return value.replace("|", r"\|").replace("\n", " ").strip()
+
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
     all_ok = all(ok for ok, _ in validations)
+    package_dir = output_file.parent
+    upload_md_dir = package_dir / "upload-md"
 
     lines = [
-        "# PACKAGES INDEX",
+        "# Packages Index",
         "",
-        f"- Generated: {ts}",
+        "## Snapshot",
+        "",
+        f"- Generated (UTC): **{ts}**",
         f"- Skills root: `{skills_root}`",
-        f"- Valid skills packaged: {len(valid_skills)}",
-        f"- Package formats: `.skill` + `.zip` (per skill)",
-        f"- Bundle: `{bundle_path.name}`",
-        f"- Validation status: {'PASS' if all_ok else 'FAIL'}",
+        f"- Valid skills packaged: **{len(valid_skills)}**",
+        f"- Per-skill formats: `.skill` + `.zip`",
+        f"- Bundle: [`{bundle_path.name}`](bundles/{bundle_path.name})",
+        f"- Validation status: **{'PASS' if all_ok else 'FAIL'}**",
         "",
-        "## Included Skills",
+        "## Quick Links",
         "",
+        "- [Per-skill packages](per-skill/)",
+        f"- [Bundle archive](bundles/{bundle_path.name})",
+        "- [Upload markdown exports](upload-md/)",
+        "- [Skill sources](../skill/)",
+        "",
+        "## Skill Catalog",
+        "",
+        "| Skill | Description | Source | Markdown | .skill | .zip |",
+        "| --- | --- | --- | --- | --- | --- |",
     ]
 
-    for skill in valid_skills:
+    for skill in sorted(valid_skills, key=lambda item: item.package_name):
+        source_rel = f"../skill/{skill.source_dir_name}/SKILL.md"
+        markdown_rel = f"upload-md/{skill.package_name}.md"
+        skill_rel = f"per-skill/{skill.package_name}.skill"
+        zip_rel = f"per-skill/{skill.package_name}.zip"
+
+        markdown_cell = (
+            f"[`{skill.package_name}.md`]({markdown_rel})"
+            if (upload_md_dir / f"{skill.package_name}.md").exists()
+            else "N/A"
+        )
+        source_cell = (
+            f"[`{skill.source_dir_name}/SKILL.md`]({source_rel})"
+            if Path(skills_root / skill.source_dir_name / "SKILL.md").exists()
+            else "N/A"
+        )
+
         lines.append(
-            "- `{name}` (source dir: `{src}`, declared name: `{decl}`)".format(
-                name=skill.package_name, src=skill.source_dir_name, decl=skill.declared_name
+            "| `{name}` | {description} | {source} | {markdown} | [`{name}.skill`]({skill_pkg}) | [`{name}.zip`]({zip_pkg}) |".format(
+                name=skill.package_name,
+                description=table_safe(skill.description),
+                source=source_cell,
+                markdown=markdown_cell,
+                skill_pkg=skill_rel,
+                zip_pkg=zip_rel,
             )
         )
 
+    lines.extend(["", "## Validation"])
+    lines.extend(
+        [f"- [{'x' if ok else ' '}] {message}" for ok, message in validations]
+    )
+
     lines.extend(["", "## Warnings", ""])
     if warnings:
         lines.extend([f"- {msg}" for msg in warnings])
@@ -166,11 +208,16 @@ def build_index(
     else:
         lines.append("- None")
 
-    lines.extend(["", "## Validation", ""])
-    for ok, message in validations:
-        lines.append(f"- [{'x' if ok else ' '}] {message}")
-
-    lines.extend(["", "## Output Paths", "", "- `package/per-skill/`", "- `package/bundles/`"])
+    lines.extend(
+        [
+            "",
+            "## Output Paths",
+            "",
+            "- [`package/per-skill/`](per-skill/)",
+            "- [`package/bundles/`](bundles/)",
+            "- [`package/upload-md/`](upload-md/)",
+        ]
+    )
     output_file.write_text("\n".join(lines) + "\n", encoding="utf-8")