feat: Add SkillMapper display overlay for skill ID, description, and tags, and remove the unused _build_extensions() method and its documentation.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-23
+
+### Added
+
+- **Display overlay in `SkillMapper`** (§5.13) — `to_skill()` reads `metadata["display"]["a2a"]` for skill id, description, and tags when present.
+  - Skill id: `metadata["display"]["a2a"]["alias"]` → `metadata["display"]["alias"]` → `module_id`.
+  - Description: `metadata["display"]["a2a"]["description"]` → `metadata["display"]["description"]` → `module.description`.
+  - Tags: `metadata["display"]["tags"]` → `module.tags`.
+- Updated feature spec: `docs/features/adapters.md` — SkillMapper field mapping table updated, `_build_extensions` noted as removed.
+
+### Removed
+
+- **`_build_extensions()` dead code** — `AgentSkill` has no `extensions` field in the A2A SDK; this method could never be wired in. Deleted along with its 3 tests.
+
+### Changed
+
+- Dependency bump: requires `apcore-toolkit >= 0.4.0` for `DisplayResolver`.
+
+### Tests
+
+- `TestSkillMapperDisplayOverlay` (6 tests): A2A alias used as skill id, A2A description used, tags from display overlay, surface-specific override wins, fallback to scanner values when no overlay.
+- Removed 3 `test__build_extensions_*` tests (dead code).
+
+---
+
 ## [0.2.1] - 2026-03-22
 
 ### Changed

docs/features/adapters.md

@@ -100,21 +100,20 @@ class SkillMapper:
     def _compute_input_modes(self, descriptor: object) -> list[str]: ...
     def _compute_output_modes(self, descriptor: object) -> list[str]: ...
     def _build_examples(self, descriptor: object) -> list[str]: ...  # max 10, title strings only
-    def _build_extensions(self, annotations: object | None) -> dict | None: ...
+    # Note: _build_extensions() was removed — AgentSkill has no `extensions` field in a2a-sdk
 ```
 
 **Field mapping:**
 
 | apcore field | A2A Skill field | Notes |
 |---|---|---|
-| `module_id` | `id` | Verbatim |
-| humanize(`module_id`) | `name` | Dots/underscores → spaces, title case |
-| `description` | `description` | Verbatim. Empty/None → return `None` |
-| `tags` | `tags` | Verbatim |
+| `metadata["display"]["a2a"]["alias"]` or `metadata["display"]["alias"]` or `module_id` | `id` | Display overlay alias takes priority |
+| `metadata["display"]["a2a"]["description"]` or `metadata["display"]["description"]` or `description` | `description` | Display overlay description takes priority. Empty/None → return `None` |
+| `metadata["display"]["tags"]` or `tags` | `tags` | Display overlay tags take priority |
 | `examples[:10]` | `examples` | `title` → `name`, `inputs` → JSON string in TextPart |
 | computed | `inputModes` | See mode logic below |
 | computed | `outputModes` | See mode logic below |
-| `annotations` | *(not mapped)* | `_build_extensions()` exists but `a2a.types.AgentSkill` has no `extensions` field; annotations are available via the Explorer UI's `_inputSchemas` enrichment instead |
+| `annotations` | *(not mapped)* | See note below |
 
 **Input/output mode logic:**
 
@@ -126,17 +125,7 @@ class SkillMapper:
 | `output_schema` defined | | `["application/json"]` |
 | No `output_schema` | | `["text/plain"]` |
 
-**Extensions structure (when annotations is not None):**
-```json
-{
-  "apcore": {
-    "annotations": {
-      "readonly": false, "destructive": false, "idempotent": false,
-      "requires_approval": false, "open_world": true
-    }
-  }
-}
-```
+**Note on annotations:** `_build_extensions()` has been removed. `a2a.types.AgentSkill` has no `extensions` field in the A2A SDK; apcore annotations are available via the Explorer UI's `_inputSchemas` enrichment instead.
 
 ---