feat: enforce Hermes skill and provider contracts

AGENTS.md

@@ -57,6 +57,9 @@ plugin.
   dictionaries unless deliberately returning an already-encoded string.
 - Keep validation errors instructive for model-facing callers, including the
   missing argument name and example when available.
+- Keep stateful Hermes provider ABCs as provider instances: register memory,
+  image-generation, and video-generation providers through their specialized
+  contexts instead of decorating provider methods as general plugin surfaces.
 - Redact secret-looking values in logs and avoid logging full untrusted payloads.
 - Use `uv` and the Makefile for local development:
   `make install`, `make test`, `make test-one T=tests.test_kit.SchemaConventionTests`,

README.md

@@ -447,6 +447,60 @@ deliver_media(
 )
 ```
 
+`plugin_skill` reads and validates the referenced file immediately, then checks
+it again during registration. Every required skill must contain closed YAML
+frontmatter, a non-empty body, matching `name` and `description` values, and
+well-shaped Hermes metadata. Optional missing files remain skippable; if an
+optional file exists, it must satisfy the same contract.
+
+```yaml
+---
+name: temporal-awareness
+description: Calibrate responses against local time and message gaps.
+platforms: [macos, linux]
+metadata:
+  hermes:
+    tags: [Time, Context]
+    requires_toolsets: [terminal]
+---
+```
+
+The validator covers Hermes platform, conditional activation, config,
+blueprint, environment-variable, and credential-file metadata shapes. Runtime
+activation and setup behavior remain owned by Hermes Agent.
+
+## Subagents and specialized providers
+
+Subagent lifecycle supervision is host-owned. Use the checked accessor instead
+of importing delegation internals:
+
+```python
+from agent.subagent_lifecycle import SubagentLaunchRequest
+from hermes_plugin_kit import get_subagent_lifecycle
+
+service = get_subagent_lifecycle(ctx)
+handle = service.launch(SubagentLaunchRequest(goal="Review this change."))
+```
+
+Memory, image-generation, and video-generation providers remain instances of
+their Hermes ABCs. Pass them to `register_plugin`; the kit validates the common
+identity seam and forwards each instance to the specialized context registry:
+
+```python
+return register_plugin(
+    ctx,
+    (),
+    memory_providers=(MyMemoryProvider(),),
+    image_gen_providers=(MyImageGenProvider(),),
+    video_gen_providers=(MyVideoGenProvider(),),
+)
+```
+
+Memory providers must run through Hermes' memory-provider discovery context.
+Image and video providers run through the general `PluginContext`. The kit does
+not decorate provider methods or replace the `MemoryProvider`,
+`ImageGenProvider`, or `VideoGenProvider` contracts.
+
 The ordinary path remains Hermes' host-managed `send_message`. Because that
 host contract does not currently expose Telegram's `has_spoiler`, only
 `spoiler=True` uses the kit's narrow Telegram extension. The extension accepts
@@ -515,6 +569,20 @@ The kit never logs handler result payloads. Keys containing `token`, `secret`,
 `password`, `passwd`, `api_key`, `apikey`, or `auth` are replaced with `***` at
 any nesting depth before arguments are logged.
 
+## Agent skills
+
+Repository-owned skills are consumable directly from [`skills/`](skills). To
+make the Agent Plugins migration skill available to Codex while keeping this
+repository as the source of truth:
+
+```bash
+ln -s "$(pwd)/skills/migrate-agent-plugin" ~/.codex/skills/migrate-agent-plugin
+```
+
+Remove or rename an existing destination before creating the link. The skill
+includes its migration guide, client-extension rules, and validation checklist,
+so the linked directory is self-contained.
+
 ## Development
 
 Uses [uv](https://docs.astral.sh/uv/). Install it with `brew install uv` (macOS) or