feat(skills): add skill docs and upgrade metadata

Extend skill candidate create/read flows with optional summary, usage
notes, and structured pre/post conditions.

Add release promotion metadata fields for upgrade lineage and change
context, including parent release ID, upgrade reason, and change
summary.

Propagate these fields through Bay API models/services, SDK types and
client methods, MCP handlers/tool schemas, and integration/unit tests.

Author: RC-CHN

pkgs/bay/app/api/v1/skills.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from datetime import datetime
 from typing import Any
 
@@ -22,6 +23,10 @@ class SkillCandidateCreateRequest(BaseModel):
     source_execution_ids: list[str]
     scenario_key: str | None = None
     payload_ref: str | None = None
+    summary: str | None = None
+    usage_notes: str | None = None
+    preconditions: dict[str, Any] | None = None
+    postconditions: dict[str, Any] | None = None
 
 
 class SkillCandidateResponse(BaseModel):
@@ -34,6 +39,10 @@ class SkillCandidateResponse(BaseModel):
     skill_type: str
     auto_release_eligible: bool
     auto_release_reason: str | None
+    summary: str | None
+    usage_notes: str | None
+    preconditions: dict[str, Any] | None
+    postconditions: dict[str, Any] | None
     source_execution_ids: list[str]
     status: str
     latest_score: float | None
@@ -78,6 +87,9 @@ class SkillPromotionRequest(BaseModel):
     """Promotion request."""
 
     stage: str = SkillReleaseStage.CANARY.value
+    upgrade_of_release_id: str | None = None
+    upgrade_reason: str | None = None
+    change_summary: str | None = None
 
 
 class SkillReleaseResponse(BaseModel):
@@ -95,6 +107,9 @@ class SkillReleaseResponse(BaseModel):
     rollback_of: str | None
     auto_promoted_from: str | None
     health_window_end_at: datetime | None
+    upgrade_of_release_id: str | None
+    upgrade_reason: str | None
+    change_summary: str | None
 
 
 class SkillReleaseHealthResponse(BaseModel):
@@ -150,6 +165,16 @@ class SkillPayloadResponse(BaseModel):
     payload: dict[str, Any] | list[Any]
 
 
+def _json_field_to_obj(raw: str | None) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
 def _candidate_to_response(candidate) -> SkillCandidateResponse:
     source_execution_ids = [item for item in candidate.source_execution_ids.split(",") if item]
     return SkillCandidateResponse(
@@ -160,6 +185,10 @@ def _candidate_to_response(candidate) -> SkillCandidateResponse:
         skill_type=candidate.skill_type.value,
         auto_release_eligible=candidate.auto_release_eligible,
         auto_release_reason=candidate.auto_release_reason,
+        summary=candidate.summary,
+        usage_notes=candidate.usage_notes,
+        preconditions=_json_field_to_obj(candidate.preconditions_json),
+        postconditions=_json_field_to_obj(candidate.postconditions_json),
         source_execution_ids=source_execution_ids,
         status=candidate.status.value,
         latest_score=candidate.latest_score,
@@ -199,6 +228,9 @@ def _release_to_response(release) -> SkillReleaseResponse:
         rollback_of=release.rollback_of,
         auto_promoted_from=release.auto_promoted_from,
         health_window_end_at=release.health_window_end_at,
+        upgrade_of_release_id=release.upgrade_of_release_id,
+        upgrade_reason=release.upgrade_reason,
+        change_summary=release.change_summary,
     )
 
 
@@ -248,6 +280,10 @@ async def create_candidate(
         source_execution_ids=request.source_execution_ids,
         scenario_key=request.scenario_key,
         payload_ref=request.payload_ref,
+        summary=request.summary,
+        usage_notes=request.usage_notes,
+        preconditions=request.preconditions,
+        postconditions=request.postconditions,
         created_by=owner,
     )
     return _candidate_to_response(candidate)
@@ -327,6 +363,9 @@ async def promote_candidate(
         candidate_id=candidate_id,
         stage=stage,
         promoted_by=owner,
+        upgrade_of_release_id=request.upgrade_of_release_id,
+        upgrade_reason=request.upgrade_reason,
+        change_summary=request.change_summary,
     )
     return _release_to_response(release)
 

pkgs/bay/app/models/skill.py

@@ -127,6 +127,12 @@ class SkillCandidate(SQLModel, table=True):
     auto_release_eligible: bool = Field(default=False, index=True)
     auto_release_reason: str | None = Field(default=None)
 
+    # Human-readable skill documentation fields.
+    summary: str | None = Field(default=None)
+    usage_notes: str | None = Field(default=None)
+    preconditions_json: str | None = Field(default=None)
+    postconditions_json: str | None = Field(default=None)
+
     # Comma-separated execution IDs used as source evidence.
     source_execution_ids: str = Field(default="")
 
@@ -184,3 +190,8 @@ class SkillRelease(SQLModel, table=True):
     rollback_of: str | None = Field(default=None, index=True)
     auto_promoted_from: str | None = Field(default=None, index=True)
     health_window_end_at: datetime | None = Field(default=None, index=True)
+
+    # Human-readable release-upgrade metadata.
+    upgrade_of_release_id: str | None = Field(default=None, index=True)
+    upgrade_reason: str | None = Field(default=None)
+    change_summary: str | None = Field(default=None)

pkgs/bay/app/services/skills/service.py

@@ -419,6 +419,10 @@ async def create_candidate(
         source_execution_ids: list[str],
         scenario_key: str | None = None,
         payload_ref: str | None = None,
+        summary: str | None = None,
+        usage_notes: str | None = None,
+        preconditions: dict[str, Any] | None = None,
+        postconditions: dict[str, Any] | None = None,
         created_by: str | None = None,
         skill_type: SkillType = SkillType.CODE,
         auto_release_eligible: bool = False,
@@ -442,6 +446,16 @@ async def create_candidate(
             skill_type=skill_type,
             auto_release_eligible=auto_release_eligible,
             auto_release_reason=auto_release_reason,
+            summary=summary,
+            usage_notes=usage_notes,
+            preconditions_json=(
+                json.dumps(preconditions, ensure_ascii=False) if preconditions is not None else None
+            ),
+            postconditions_json=(
+                json.dumps(postconditions, ensure_ascii=False)
+                if postconditions is not None
+                else None
+            ),
             status=SkillCandidateStatus.DRAFT,
             created_by=created_by,
             created_at=utcnow(),
@@ -587,6 +601,9 @@ async def promote_candidate(
         release_mode: SkillReleaseMode = SkillReleaseMode.MANUAL,
         auto_promoted_from: str | None = None,
         health_window_end_at: datetime | None = None,
+        upgrade_of_release_id: str | None = None,
+        upgrade_reason: str | None = None,
+        change_summary: str | None = None,
     ) -> SkillRelease:
         candidate = await self.get_candidate(owner=owner, candidate_id=candidate_id)
 
@@ -628,6 +645,9 @@ async def promote_candidate(
             promoted_at=utcnow(),
             auto_promoted_from=auto_promoted_from,
             health_window_end_at=health_window_end_at,
+            upgrade_of_release_id=upgrade_of_release_id,
+            upgrade_reason=upgrade_reason,
+            change_summary=change_summary,
         )
         self._db.add(release)
 

pkgs/bay/tests/integration/core/test_skill_lifecycle_api.py

@@ -42,12 +42,20 @@ async def test_candidate_evaluate_promote_and_rollback_flow():
                     "source_execution_ids": [exec_a],
                     "scenario_key": "etl.csv",
                     "payload_ref": "s3://skills/csv-loader/a",
+                    "summary": "Load CSV into warehouse",
+                    "usage_notes": "Requires warehouse credentials",
+                    "preconditions": {"runtime": "python"},
+                    "postconditions": {"table": "created"},
                 },
             )
             assert create_a.status_code == 201
             candidate_a = create_a.json()
             assert candidate_a["status"] == "draft"
             assert candidate_a["source_execution_ids"] == [exec_a]
+            assert candidate_a["summary"] == "Load CSV into warehouse"
+            assert candidate_a["usage_notes"] == "Requires warehouse credentials"
+            assert candidate_a["preconditions"] == {"runtime": "python"}
+            assert candidate_a["postconditions"] == {"table": "created"}
 
             evaluate_a = await client.post(
                 f"/v1/skills/candidates/{candidate_a['id']}/evaluate",
@@ -63,14 +71,21 @@ async def test_candidate_evaluate_promote_and_rollback_flow():
 
             promote_a = await client.post(
                 f"/v1/skills/candidates/{candidate_a['id']}/promote",
-                json={"stage": "stable"},
+                json={
+                    "stage": "stable",
+                    "upgrade_reason": "manual_promote",
+                    "change_summary": "Baseline stable release",
+                },
             )
             assert promote_a.status_code == 200
             release_a = promote_a.json()
             assert release_a["skill_key"] == "csv-loader"
             assert release_a["version"] == 1
             assert release_a["stage"] == "stable"
             assert release_a["is_active"] is True
+            assert release_a["upgrade_reason"] == "manual_promote"
+            assert release_a["change_summary"] == "Baseline stable release"
+            assert release_a["upgrade_of_release_id"] is None
 
             exec_b = await _create_python_execution(client, sandbox_id, "print('candidate-b')")
             create_b = await client.post(
@@ -91,12 +106,19 @@ async def test_candidate_evaluate_promote_and_rollback_flow():
             assert evaluate_b.status_code == 200
             promote_b = await client.post(
                 f"/v1/skills/candidates/{candidate_b['id']}/promote",
-                json={"stage": "canary"},
+                json={
+                    "stage": "canary",
+                    "upgrade_of_release_id": release_a["id"],
+                    "upgrade_reason": "metric_improved",
+                    "change_summary": "Improved parsing accuracy",
+                },
             )
             assert promote_b.status_code == 200
             release_b = promote_b.json()
             assert release_b["version"] == 2
             assert release_b["is_active"] is True
+            assert release_b["upgrade_of_release_id"] == release_a["id"]
+            assert release_b["upgrade_reason"] == "metric_improved"
 
             list_active = await client.get(
                 "/v1/skills/releases",

shipyard-neo-mcp/src/shipyard_neo_mcp/handlers/skills.py

@@ -75,6 +75,18 @@ async def handle_create_skill_candidate(
             source_execution_ids=source_execution_ids,
             scenario_key=optional_str(arguments, "scenario_key"),
             payload_ref=optional_str(arguments, "payload_ref"),
+            summary=optional_str(arguments, "summary"),
+            usage_notes=optional_str(arguments, "usage_notes"),
+            preconditions=(
+                arguments.get("preconditions")
+                if isinstance(arguments.get("preconditions"), dict)
+                else None
+            ),
+            postconditions=(
+                arguments.get("postconditions")
+                if isinstance(arguments.get("postconditions"), dict)
+                else None
+            ),
         )
     return [
         TextContent(
@@ -129,6 +141,9 @@ async def handle_promote_skill_candidate(
         release = await client.skills.promote_candidate(
             candidate_id,
             stage=read_release_stage(arguments, key="stage", default="canary"),
+            upgrade_of_release_id=optional_str(arguments, "upgrade_of_release_id"),
+            upgrade_reason=optional_str(arguments, "upgrade_reason"),
+            change_summary=optional_str(arguments, "change_summary"),
         )
     return [
         TextContent(
@@ -139,7 +154,9 @@ async def handle_promote_skill_candidate(
                 f"skill_key: {release.skill_key}\n"
                 f"version: {release.version}\n"
                 f"stage: {release.stage.value}\n"
-                f"active: {release.is_active}"
+                f"active: {release.is_active}\n"
+                f"upgrade_of_release_id: {getattr(release, 'upgrade_of_release_id', None)}\n"
+                f"upgrade_reason: {getattr(release, 'upgrade_reason', None)}"
             ),
         )
     ]

shipyard-neo-mcp/src/shipyard_neo_mcp/tool_defs.py

@@ -311,7 +311,7 @@ def get_tool_definitions() -> list[Tool]:
         ),
         Tool(
             name="create_skill_candidate",
-            description="Create a reusable skill candidate from execution IDs.",
+            description="Create a reusable skill candidate from execution IDs, with optional human-readable summary/notes and pre/post conditions.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -329,6 +329,22 @@ def get_tool_definitions() -> list[Tool]:
                         "type": "string",
                         "description": "Optional payload reference.",
                     },
+                    "summary": {
+                        "type": "string",
+                        "description": "Optional human-readable skill summary.",
+                    },
+                    "usage_notes": {
+                        "type": "string",
+                        "description": "Optional usage notes for operators/agents.",
+                    },
+                    "preconditions": {
+                        "type": "object",
+                        "description": "Optional JSON object describing preconditions.",
+                    },
+                    "postconditions": {
+                        "type": "object",
+                        "description": "Optional JSON object describing postconditions.",
+                    },
                 },
                 "required": ["skill_key", "source_execution_ids"],
             },
@@ -365,7 +381,7 @@ def get_tool_definitions() -> list[Tool]:
         ),
         Tool(
             name="promote_skill_candidate",
-            description="Promote a passing skill candidate to release.",
+            description="Promote a passing skill candidate to release, with optional upgrade metadata (parent release, reason, and change summary).",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -377,6 +393,18 @@ def get_tool_definitions() -> list[Tool]:
                         "type": "string",
                         "description": "Release stage: canary or stable. Defaults to canary.",
                     },
+                    "upgrade_of_release_id": {
+                        "type": "string",
+                        "description": "Optional parent release ID this promotion upgrades from.",
+                    },
+                    "upgrade_reason": {
+                        "type": "string",
+                        "description": "Optional reason for this promotion/upgrade.",
+                    },
+                    "change_summary": {
+                        "type": "string",
+                        "description": "Optional human-readable change summary.",
+                    },
                 },
                 "required": ["candidate_id"],
             },