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

package/PACKAGES_INDEX.md

@@ -1,59 +1,61 @@
-# PACKAGES INDEX
+# Packages Index
 
-- Generated: 2026-03-19 14:05:51 UTC
+## Snapshot
+
+- Generated (UTC): **2026-03-19 14:13:09 UTC**
 - Skills root: `/home/davide/cev-skills/skill`
-- Valid skills packaged: 34
-- Package formats: `.skill` + `.zip` (per skill)
-- Bundle: `mechanical-skills-collection.zip`
-- Validation status: PASS
+- Valid skills packaged: **34**
+- Per-skill formats: `.skill` + `.zip`
+- Bundle: [`mechanical-skills-collection.zip`](bundles/mechanical-skills-collection.zip)
+- Validation status: **PASS**
 
-## Included Skills
+## Quick Links
 
-- `bearings-seals-selection` (source dir: `bearings-seals-selection`, declared name: `bearings-seals-selection`)
-- `calculation-report` (source dir: `calculation-report`, declared name: `calculation-report`)
-- `cnc-sheet-casting-forging` (source dir: `cnc-sheet-casting-forging`, declared name: `cnc-sheet-casting-forging`)
-- `design-review-fmea` (source dir: `design-review-fmea`, declared name: `design-review-fmea`)
-- `dfm-dfa-review` (source dir: `dfm-dfa-review`, declared name: `dfm-dfa-review`)
-- `dynamics-vibrations-analysis` (source dir: `dynamics-vibrations-analysis`, declared name: `dynamics-vibrations-analysis`)
-- `energy-efficiency-analysis` (source dir: `energy-efficiency-analysis`, declared name: `energy-efficiency-analysis`)
-- `failure-root-cause-analysis` (source dir: `failure-root-cause-analysis`, declared name: `failure-root-cause-analysis`)
-- `fatigue-fracture-analysis` (source dir: `fatigue-fracture-analysis`, declared name: `fatigue-fracture-analysis`)
-- `fea-cfd-review` (source dir: `fea-cfd-review`, declared name: `fea-cfd-review`)
-- `fluid-analysis` (source dir: `fluid-analysis`, declared name: `fluid-analysis`)
-- `gear-design` (source dir: `gear-design`, declared name: `gear-design`)
-- `heat-treatment` (source dir: `heat-treatment`, declared name: `heat-treatment`)
-- `joints-design` (source dir: `joints-design`, declared name: `joints-design`)
-- `machine-elements-selection` (source dir: `machine-elements-selection`, declared name: `machine-elements-selection`)
-- `material-failure-modes` (source dir: `material-failure-modes`, declared name: `material-failure-modes`)
-- `materials-metallurgy` (source dir: `materials-metallurgy`, declared name: `materials-metallurgy`)
-- `mechanical-orchestrator` (source dir: `mechanical-orchestrator`, declared name: `mechanical-orchestrator`)
-- `modal-analysis` (source dir: `modal-analysis`, declared name: `modal-analysis`)
-- `pressure-loss-pump-piping` (source dir: `pressure-loss-pump-piping`, declared name: `pressure-loss-pump-piping`)
-- `process-selection` (source dir: `process-selection`, declared name: `process-selection`)
-- `quality-metrology-plan` (source dir: `quality-metrology-plan`, declared name: `quality-metrology-plan`)
-- `reliability-analysis` (source dir: `reliability-analysis`, declared name: `reliability-analysis`)
-- `shafts-couplings-design` (source dir: `shafts-couplings-design`, declared name: `shafts-couplings-design`)
-- `should-cost-estimation` (source dir: `should-cost-estimation`, declared name: `should-cost-estimation`)
-- `spring-design` (source dir: `spring-design`, declared name: `spring-design`)
-- `standards-compliance-check` (source dir: `standards-compliance-check`, declared name: `standards-compliance-check`)
-- `structural-analysis` (source dir: `structural-analysis`, declared name: `structural-analysis`)
-- `technical-report` (source dir: `technical-report`, declared name: `technical-report`)
-- `test-plan-validation` (source dir: `test-plan-validation`, declared name: `test-plan-validation`)
-- `thermal-analysis` (source dir: `thermal-analysis`, declared name: `thermal-analysis`)
-- `thermal-expansion-stress` (source dir: `thermal-expansion-stress`, declared name: `thermal-expansion-stress`)
-- `tolerance-gdt-fits` (source dir: `tolerance-gdt-fits`, declared name: `tolerance-gdt-fits`)
-- `tribology-lubrication` (source dir: `tribology-lubrication`, declared name: `tribology-lubrication`)
+- [Per-skill packages](per-skill/)
+- [Bundle archive](bundles/mechanical-skills-collection.zip)
+- [Upload markdown exports](upload-md/)
+- [Skill sources](../skill/)
 
-## Warnings
+## Skill Catalog
 
-- None
-
-## Skipped
-
-- None
+| Skill | Description | Source | Markdown | .skill | .zip |
+| --- | --- | --- | --- | --- | --- |
+| `bearings-seals-selection` | Bearing and seal selection for rotating equipment. Use this skill whenever the user asks about bearing type/life, preload, lubrication, sealing, contamination control, or shaft support architecture. | [`bearings-seals-selection/SKILL.md`](../skill/bearings-seals-selection/SKILL.md) | [`bearings-seals-selection.md`](upload-md/bearings-seals-selection.md) | [`bearings-seals-selection.skill`](per-skill/bearings-seals-selection.skill) | [`bearings-seals-selection.zip`](per-skill/bearings-seals-selection.zip) |
+| `calculation-report` | Calculation report preparation for auditable engineering calculations. Use this skill whenever the user needs formal calculation packs with equations, assumptions, units, and compliance-ready traceability. | [`calculation-report/SKILL.md`](../skill/calculation-report/SKILL.md) | [`calculation-report.md`](upload-md/calculation-report.md) | [`calculation-report.skill`](per-skill/calculation-report.skill) | [`calculation-report.zip`](per-skill/calculation-report.zip) |
+| `cnc-sheet-casting-forging` | Detailed manufacturing guidance for CNC machining, sheet metal, casting, and forging. Use this skill whenever the user requests geometry rules, draft/radii, tool access, or redesign for a specific process family. | [`cnc-sheet-casting-forging/SKILL.md`](../skill/cnc-sheet-casting-forging/SKILL.md) | [`cnc-sheet-casting-forging.md`](upload-md/cnc-sheet-casting-forging.md) | [`cnc-sheet-casting-forging.skill`](per-skill/cnc-sheet-casting-forging.skill) | [`cnc-sheet-casting-forging.zip`](per-skill/cnc-sheet-casting-forging.zip) |
+| `design-review-fmea` | Structured design review and FMEA for risk reduction. Use this skill whenever the user asks for design review checklists, failure prevention planning, or prioritization of design risks before release. | [`design-review-fmea/SKILL.md`](../skill/design-review-fmea/SKILL.md) | [`design-review-fmea.md`](upload-md/design-review-fmea.md) | [`design-review-fmea.skill`](per-skill/design-review-fmea.skill) | [`design-review-fmea.zip`](per-skill/design-review-fmea.zip) |
+| `dfm-dfa-review` | Design for manufacturing and assembly review for mechanical products. Use this skill whenever the user asks if a design is producible/assemblable, wants part-count reduction, or needs robust assembly flow. | [`dfm-dfa-review/SKILL.md`](../skill/dfm-dfa-review/SKILL.md) | [`dfm-dfa-review.md`](upload-md/dfm-dfa-review.md) | [`dfm-dfa-review.skill`](per-skill/dfm-dfa-review.skill) | [`dfm-dfa-review.zip`](per-skill/dfm-dfa-review.zip) |
+| `dynamics-vibrations-analysis` | Rigid-body dynamics and vibration response analysis. Use this skill whenever the user asks about motion, acceleration loads, resonance, transmissibility, balancing, or dynamic amplification in machines. | [`dynamics-vibrations-analysis/SKILL.md`](../skill/dynamics-vibrations-analysis/SKILL.md) | [`dynamics-vibrations-analysis.md`](upload-md/dynamics-vibrations-analysis.md) | [`dynamics-vibrations-analysis.skill`](per-skill/dynamics-vibrations-analysis.skill) | [`dynamics-vibrations-analysis.zip`](per-skill/dynamics-vibrations-analysis.zip) |
+| `energy-efficiency-analysis` | Energy efficiency optimization for mechanical and thermo-fluid systems. Use this skill whenever the user wants to reduce energy consumption, compare efficiency options, or evaluate lifecycle energy impact of design choices. | [`energy-efficiency-analysis/SKILL.md`](../skill/energy-efficiency-analysis/SKILL.md) | [`energy-efficiency-analysis.md`](upload-md/energy-efficiency-analysis.md) | [`energy-efficiency-analysis.skill`](per-skill/energy-efficiency-analysis.skill) | [`energy-efficiency-analysis.zip`](per-skill/energy-efficiency-analysis.zip) |
+| `failure-root-cause-analysis` | Root cause analysis for field or test failures in mechanical systems. Use this skill whenever the user asks why a failure happened, needs 5-Why/fishbone evidence, or must define corrective actions. | [`failure-root-cause-analysis/SKILL.md`](../skill/failure-root-cause-analysis/SKILL.md) | [`failure-root-cause-analysis.md`](upload-md/failure-root-cause-analysis.md) | [`failure-root-cause-analysis.skill`](per-skill/failure-root-cause-analysis.skill) | [`failure-root-cause-analysis.zip`](per-skill/failure-root-cause-analysis.zip) |
+| `fatigue-fracture-analysis` | Fatigue life and fracture risk assessment for cyclic loading. Use this skill whenever the user mentions S-N life, crack growth, endurance, variable amplitude cycles, weld fatigue, or brittle/ductile fracture concerns, even if test data is limited. | [`fatigue-fracture-analysis/SKILL.md`](../skill/fatigue-fracture-analysis/SKILL.md) | [`fatigue-fracture-analysis.md`](upload-md/fatigue-fracture-analysis.md) | [`fatigue-fracture-analysis.skill`](per-skill/fatigue-fracture-analysis.skill) | [`fatigue-fracture-analysis.zip`](per-skill/fatigue-fracture-analysis.zip) |
+| `fea-cfd-review` | Critical review of FEA/CFD models and simulation credibility. Use this skill whenever the user asks to validate simulation setup/results, challenge assumptions, or decide if analysis is decision-ready. | [`fea-cfd-review/SKILL.md`](../skill/fea-cfd-review/SKILL.md) | [`fea-cfd-review.md`](upload-md/fea-cfd-review.md) | [`fea-cfd-review.skill`](per-skill/fea-cfd-review.skill) | [`fea-cfd-review.zip`](per-skill/fea-cfd-review.zip) |
+| `fluid-analysis` | Internal and external fluid flow analysis for engineering systems. Use this skill whenever the user asks about flow rate, pressure drop, Reynolds regime, valve/piping behavior, or fluid-system sizing. | [`fluid-analysis/SKILL.md`](../skill/fluid-analysis/SKILL.md) | [`fluid-analysis.md`](upload-md/fluid-analysis.md) | [`fluid-analysis.skill`](per-skill/fluid-analysis.skill) | [`fluid-analysis.zip`](per-skill/fluid-analysis.zip) |
+| `gear-design` | Gear train design and verification for power transmission. Use this skill whenever the user asks about gear geometry, ratio selection, tooth stresses, micropitting/scuffing, or gearbox design tradeoffs. | [`gear-design/SKILL.md`](../skill/gear-design/SKILL.md) | [`gear-design.md`](upload-md/gear-design.md) | [`gear-design.skill`](per-skill/gear-design.skill) | [`gear-design.zip`](per-skill/gear-design.zip) |
+| `heat-treatment` | Heat-treatment strategy for steels and alloys in mechanical design. Use this skill whenever the user asks about hardening, tempering, case depth, residual stresses, distortion, or hardness-toughness tradeoffs. | [`heat-treatment/SKILL.md`](../skill/heat-treatment/SKILL.md) | [`heat-treatment.md`](upload-md/heat-treatment.md) | [`heat-treatment.skill`](per-skill/heat-treatment.skill) | [`heat-treatment.zip`](per-skill/heat-treatment.zip) |
+| `joints-design` | Joint design for bolts, welds, adhesives, and hybrid joints. Use this skill whenever the user asks how to join parts or verify joint integrity under static, fatigue, thermal, or corrosive conditions. | [`joints-design/SKILL.md`](../skill/joints-design/SKILL.md) | [`joints-design.md`](upload-md/joints-design.md) | [`joints-design.skill`](per-skill/joints-design.skill) | [`joints-design.zip`](per-skill/joints-design.zip) |
+| `machine-elements-selection` | Integrated selection of machine elements for a mechanism or subsystem. Use this skill whenever the user asks to choose among bearings/gears/springs/joints/couplings under constraints of reliability, cost, and manufacturability. | [`machine-elements-selection/SKILL.md`](../skill/machine-elements-selection/SKILL.md) | [`machine-elements-selection.md`](upload-md/machine-elements-selection.md) | [`machine-elements-selection.skill`](per-skill/machine-elements-selection.skill) | [`machine-elements-selection.zip`](per-skill/machine-elements-selection.zip) |
+| `material-failure-modes` | Material failure mode identification and prevention. Use this skill whenever the user asks about yielding, brittle fracture, creep, wear, corrosion-assisted cracking, or unexplained material degradation. | [`material-failure-modes/SKILL.md`](../skill/material-failure-modes/SKILL.md) | [`material-failure-modes.md`](upload-md/material-failure-modes.md) | [`material-failure-modes.skill`](per-skill/material-failure-modes.skill) | [`material-failure-modes.zip`](per-skill/material-failure-modes.zip) |
+| `materials-metallurgy` | Materials engineering and metallurgy guidance for design decisions. Use this skill whenever the user asks to choose metals/polymers/composites, compare material behavior, or evaluate metallurgical effects on performance. | [`materials-metallurgy/SKILL.md`](../skill/materials-metallurgy/SKILL.md) | [`materials-metallurgy.md`](upload-md/materials-metallurgy.md) | [`materials-metallurgy.skill`](per-skill/materials-metallurgy.skill) | [`materials-metallurgy.zip`](per-skill/materials-metallurgy.zip) |
+| `mechanical-orchestrator` | Cross-domain mechanical engineering orchestration for complex design questions. Use this skill whenever a request spans multiple domains (stress, fatigue, thermal, fluid, materials, manufacturing, reliability), whenever requirements are incomplete, or whenever the user asks for a senior-level decision path and prioritization, even if they do not ask for an orchestrator explicitly. | [`mechanical-orchestrator/SKILL.md`](../skill/mechanical-orchestrator/SKILL.md) | [`mechanical-orchestrator.md`](upload-md/mechanical-orchestrator.md) | [`mechanical-orchestrator.skill`](per-skill/mechanical-orchestrator.skill) | [`mechanical-orchestrator.zip`](per-skill/mechanical-orchestrator.zip) |
+| `modal-analysis` | Modal behavior assessment for structures and assemblies. Use this skill whenever the user asks for mode shapes, eigenfrequencies, modal participation, or resonance avoidance strategies in design. | [`modal-analysis/SKILL.md`](../skill/modal-analysis/SKILL.md) | [`modal-analysis.md`](upload-md/modal-analysis.md) | [`modal-analysis.skill`](per-skill/modal-analysis.skill) | [`modal-analysis.zip`](per-skill/modal-analysis.zip) |
+| `pressure-loss-pump-piping` | Hydraulic network design including pressure losses, pumps, and piping. Use this skill whenever the user asks about line sizing, head losses, pump selection, NPSH, or piping layout effects. | [`pressure-loss-pump-piping/SKILL.md`](../skill/pressure-loss-pump-piping/SKILL.md) | [`pressure-loss-pump-piping.md`](upload-md/pressure-loss-pump-piping.md) | [`pressure-loss-pump-piping.skill`](per-skill/pressure-loss-pump-piping.skill) | [`pressure-loss-pump-piping.zip`](per-skill/pressure-loss-pump-piping.zip) |
+| `process-selection` | Manufacturing process selection across machining, forming, casting, additive, and joining. Use this skill whenever the user asks which process should be used for a part under cost, tolerance, volume, and material constraints. | [`process-selection/SKILL.md`](../skill/process-selection/SKILL.md) | [`process-selection.md`](upload-md/process-selection.md) | [`process-selection.skill`](per-skill/process-selection.skill) | [`process-selection.zip`](per-skill/process-selection.zip) |
+| `quality-metrology-plan` | Quality control and metrology planning for mechanical parts and assemblies. Use this skill whenever the user asks how to inspect, validate, or control critical characteristics in production. | [`quality-metrology-plan/SKILL.md`](../skill/quality-metrology-plan/SKILL.md) | [`quality-metrology-plan.md`](upload-md/quality-metrology-plan.md) | [`quality-metrology-plan.skill`](per-skill/quality-metrology-plan.skill) | [`quality-metrology-plan.zip`](per-skill/quality-metrology-plan.zip) |
+| `reliability-analysis` | Reliability engineering for mechanical products and systems. Use this skill whenever the user asks about reliability targets, MTBF, warranty risk, mission profiles, or reliability growth plans. | [`reliability-analysis/SKILL.md`](../skill/reliability-analysis/SKILL.md) | [`reliability-analysis.md`](upload-md/reliability-analysis.md) | [`reliability-analysis.skill`](per-skill/reliability-analysis.skill) | [`reliability-analysis.zip`](per-skill/reliability-analysis.zip) |
+| `shafts-couplings-design` | Shaft and coupling design for torque and alignment demands. Use this skill whenever the user asks about shaft sizing, keyways/splines, critical speed, misalignment, or coupling selection. | [`shafts-couplings-design/SKILL.md`](../skill/shafts-couplings-design/SKILL.md) | [`shafts-couplings-design.md`](upload-md/shafts-couplings-design.md) | [`shafts-couplings-design.skill`](per-skill/shafts-couplings-design.skill) | [`shafts-couplings-design.zip`](per-skill/shafts-couplings-design.zip) |
+| `should-cost-estimation` | Should-cost and cost-driver analysis for mechanical components. Use this skill whenever the user asks for target cost, quote sanity check, supplier negotiation inputs, or cost reduction options. | [`should-cost-estimation/SKILL.md`](../skill/should-cost-estimation/SKILL.md) | [`should-cost-estimation.md`](upload-md/should-cost-estimation.md) | [`should-cost-estimation.skill`](per-skill/should-cost-estimation.skill) | [`should-cost-estimation.zip`](per-skill/should-cost-estimation.zip) |
+| `spring-design` | Spring design for force-deflection and life requirements. Use this skill whenever the user asks about coil/leaf/disc spring sizing, stiffness tuning, set relaxation, or cycle life. | [`spring-design/SKILL.md`](../skill/spring-design/SKILL.md) | [`spring-design.md`](upload-md/spring-design.md) | [`spring-design.skill`](per-skill/spring-design.skill) | [`spring-design.zip`](per-skill/spring-design.zip) |
+| `standards-compliance-check` | Engineering standards and compliance guidance for mechanical products. Use this skill whenever the user asks about ISO/EN/ASME/ASTM/API/NACE requirements, legal/contractual compliance checks, certification readiness, or design acceptability against standards, even if standard names are only partially known. | [`standards-compliance-check/SKILL.md`](../skill/standards-compliance-check/SKILL.md) | [`standards-compliance-check.md`](upload-md/standards-compliance-check.md) | [`standards-compliance-check.skill`](per-skill/standards-compliance-check.skill) | [`standards-compliance-check.zip`](per-skill/standards-compliance-check.zip) |
+| `structural-analysis` | Solid mechanics analysis for parts and assemblies under static loads. Use this skill whenever the user asks for stress, strain, deflection, stiffness, load paths, or structural adequacy checks for mechanical components, even if geometry is incomplete. | [`structural-analysis/SKILL.md`](../skill/structural-analysis/SKILL.md) | [`structural-analysis.md`](upload-md/structural-analysis.md) | [`structural-analysis.skill`](per-skill/structural-analysis.skill) | [`structural-analysis.zip`](per-skill/structural-analysis.zip) |
+| `technical-report` | Technical report writing for mechanical engineering deliverables. Use this skill whenever the user needs a clear, professional engineering report with rationale, findings, and recommendations for stakeholders. | [`technical-report/SKILL.md`](../skill/technical-report/SKILL.md) | [`technical-report.md`](upload-md/technical-report.md) | [`technical-report.skill`](per-skill/technical-report.skill) | [`technical-report.zip`](per-skill/technical-report.zip) |
+| `test-plan-validation` | Test planning and validation strategy for mechanical design verification. Use this skill whenever the user asks how to verify requirements, design tests, set acceptance criteria, or plan DV/PV campaigns. | [`test-plan-validation/SKILL.md`](../skill/test-plan-validation/SKILL.md) | [`test-plan-validation.md`](upload-md/test-plan-validation.md) | [`test-plan-validation.skill`](per-skill/test-plan-validation.skill) | [`test-plan-validation.zip`](per-skill/test-plan-validation.zip) |
+| `thermal-analysis` | Thermal behavior analysis for mechanical systems. Use this skill whenever the user asks about temperatures, heat flux, thermal gradients, cooling, insulation, or thermal sizing of components and assemblies. | [`thermal-analysis/SKILL.md`](../skill/thermal-analysis/SKILL.md) | [`thermal-analysis.md`](upload-md/thermal-analysis.md) | [`thermal-analysis.skill`](per-skill/thermal-analysis.skill) | [`thermal-analysis.zip`](per-skill/thermal-analysis.zip) |
+| `thermal-expansion-stress` | Thermal expansion mismatch and thermal stress assessment. Use this skill whenever the user asks about differential expansion, constrained thermal growth, thermal bowing, or seal/interface thermal issues. | [`thermal-expansion-stress/SKILL.md`](../skill/thermal-expansion-stress/SKILL.md) | [`thermal-expansion-stress.md`](upload-md/thermal-expansion-stress.md) | [`thermal-expansion-stress.skill`](per-skill/thermal-expansion-stress.skill) | [`thermal-expansion-stress.zip`](per-skill/thermal-expansion-stress.zip) |
+| `tolerance-gdt-fits` | Tolerance stack-up, GD&T, and fit selection for assemblies. Use this skill whenever the user asks about dimensional variation, datums, interchangeability, fit class, or functional tolerancing. | [`tolerance-gdt-fits/SKILL.md`](../skill/tolerance-gdt-fits/SKILL.md) | [`tolerance-gdt-fits.md`](upload-md/tolerance-gdt-fits.md) | [`tolerance-gdt-fits.skill`](per-skill/tolerance-gdt-fits.skill) | [`tolerance-gdt-fits.zip`](per-skill/tolerance-gdt-fits.zip) |
+| `tribology-lubrication` | Tribology and lubrication engineering for moving interfaces. Use this skill whenever the user asks about friction, wear, lubrication regime, lubricant choice, surface finish, or seizure/scuffing risk. | [`tribology-lubrication/SKILL.md`](../skill/tribology-lubrication/SKILL.md) | [`tribology-lubrication.md`](upload-md/tribology-lubrication.md) | [`tribology-lubrication.skill`](per-skill/tribology-lubrication.skill) | [`tribology-lubrication.zip`](per-skill/tribology-lubrication.zip) |
 
 ## Validation
-
 - [x] package count check: expected 68, found 68
 - [x] bearings-seals-selection.skill: OK
 - [x] bearings-seals-selection.zip: OK
@@ -63,7 +65,16 @@
 - [x] cnc-sheet-casting-forging.zip: OK
 - [x] bundle contains all valid skill directories
 
+## Warnings
+
+- None
+
+## Skipped
+
+- None
+
 ## Output Paths
 
-- `package/per-skill/`
-- `package/bundles/`
+- [`package/per-skill/`](per-skill/)
+- [`package/bundles/`](bundles/)
+- [`package/upload-md/`](upload-md/)

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")