Add metadata-only local Skill adapter

.github/workflows/ci.yml

@@ -45,6 +45,7 @@ jobs:
 
       - name: Validate workflow, prompt, and QC contracts
         run: |
+          python -m aigc_director_kit validate-local-skill-adapter examples/local_skill_adapter_case.json --json
           python -m aigc_director_kit validate-workflow examples/skill_workflow_case.json --library examples/action_library.json --json
           python -m aigc_director_kit validate-prompt-pack examples/prompt_pack_case.json --plan examples/one_take_previs_case.json --json
           python -m aigc_director_kit validate-qc-report examples/qc_report_unverified_case.json --json

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CineThread Changelog
 
+## [0.2.3] - 2026-08-12
+
+- Added `aigc-director-local-skill-adapter`, a strict metadata-only contract for describing the interface between local Skills and CineThread.
+- Added `validate-local-skill-adapter`, a sanitized example, schema, documentation, CI coverage, and one-command public verification coverage.
+- Kept local Skill source, prompts, paths, assets, credentials, runtime execution, and media QC outside the public adapter boundary.
+
 ## [0.2.2] - 2026-08-12
 
 - Added a package version field and safe JSON report export to `verify-examples`, plus `aigc-director-kit --version`.

README.md

@@ -29,10 +29,11 @@ Windows users who do not know which Python command to use can instead double-cli
 
 ## Skill workflow handoff
 
-Local AIGC Skills can hand a sanitized workflow packet to this repository:
+Local AIGC Skills can publish a metadata-only adapter, then hand a sanitized
+workflow packet to this repository:
 
 ```text
-Skill output -> skill-workflow JSON -> validate-workflow -> optional runtime adapter
+local Skills -> metadata-only adapter -> skill-workflow JSON -> validate-workflow -> optional runtime adapter
 ```
 
 The public contract is documented in [`docs/skill-workflow-integration.md`](docs/skill-workflow-integration.md),
@@ -48,6 +49,18 @@ This is a deterministic handoff and dry-run boundary. It does not bundle
 private Skills, Blender, FFmpeg, model accounts, paid generation, or final
 video QC.
 
+The optional adapter manifest makes the boundary explicit: it maps only Skill
+labels, input/output contract names, and evidence semantics. It cannot carry
+Skill source, prompts, paths, assets, or credentials. See
+[`docs/local-skill-adapter.md`](docs/local-skill-adapter.md) and validate the
+included example with:
+
+```powershell
+python -m aigc_director_kit validate-local-skill-adapter `
+  examples/local_skill_adapter_case.json `
+  --json
+```
+
 To create one packet for an optional runtime adapter:
 
 ```powershell

docs/local-skill-adapter.md

@@ -0,0 +1,72 @@
+# Metadata-only local Skill adapter
+
+`aigc-director-local-skill-adapter` is a public manifest for describing how a
+private local Skill stack connects to CineThread. It records only stage labels,
+input and output contract names, and the meaning of each evidence state.
+
+It is deliberately not a Skill export, a prompt pack, or a project handoff.
+The manifest must stay safe to publish.
+
+## What this solves
+
+Local production Skills can be much more capable than a public repository:
+they can reason about references, direct performance, route image or video
+work, and inspect real artifacts. Publishing that implementation wholesale
+would expose private methods and make the public core harder to reproduce.
+
+The adapter manifest gives each side a small, stable boundary:
+
+```text
+private local Skills
+  -> metadata-only adapter manifest
+  -> sanitized skill-workflow packet
+  -> CineThread deterministic validation and dry-run handoff
+  -> optional runtime / real artifact
+  -> local evidence-based QC
+```
+
+The manifest is reusable across projects. A `aigc-director-skill-workflow`
+packet is project-specific and may carry a sanitized shot plan, action
+requests, prompt pack, and QC report.
+
+## Validate the public interface
+
+```powershell
+python -m aigc_director_kit validate-local-skill-adapter `
+  examples/local_skill_adapter_case.json `
+  --json
+```
+
+The example maps local stage labels to existing CineThread contracts without
+shipping any Skill instructions. It is also included in `verify-examples`.
+
+## Required public fields
+
+| Field | Meaning | Safe to publish |
+| --- | --- | --- |
+| `skill_label` | Stable label, not an installation path or source archive | Yes |
+| `role` | Short description of the stage responsibility | Yes |
+| `input_contracts` | Names of incoming interface contracts | Yes |
+| `output_contract` | Name of the outgoing CineThread or workflow contract | Yes |
+| `evidence` | `designed`, `inferred`, or `observed` evidence semantics | Yes |
+
+The manifest fixes `visibility` to `public-metadata-only` and
+`source_access` to `local-only`. Unknown fields are rejected, and obvious
+credentials or local paths in string values are rejected as a guard against
+accidental publication.
+
+That guard is structural, not a guarantee that prose is harmless. Review every
+manifest before publishing.
+
+## Keep these out
+
+- Skill source, installation paths, archives, or tool configuration;
+- prompt bodies, client briefs, private notes, or reference descriptions;
+- character and scene assets, source media, rendered output, or project IDs;
+- credentials, cookies, API keys, account identifiers, and machine paths;
+- claims that a render or QC pass happened when no artifact was inspected.
+
+Use [`skill-workflow-integration.md`](skill-workflow-integration.md) for the
+next step: emitting a sanitized, per-project workflow packet. The adapter
+manifest itself never executes a Skill, launches a runtime, renders media, or
+proves output quality.

docs/roadmap.md

@@ -6,6 +6,8 @@
   standard-library-only validators.
 - [x] A runtime adapter dry-run handoff can combine the validated plan and
   compiled action requests without launching Blender.
+- [x] A metadata-only local Skill adapter can document public integration
+  contracts without publishing local implementation details.
 - [x] The Windows example launcher accepts `AIGC_DIRECTOR_PYTHON` and checks
   common Python install locations.
 - [ ] Add an optional Blender adapter that consumes the handoff and records

docs/skill-workflow-integration.md

@@ -38,6 +38,24 @@ The example uses `aigc-manga-video-director`, `audio-to-prompt`, and
 `aigc-project-prompt-loop` as illustrative stage labels. They are not bundled
 with this Python package and can be replaced by another workflow producer.
 
+## Metadata-only local Skill adapter
+
+Before a project-specific workflow packet exists, a local workflow may publish
+an `aigc-director-local-skill-adapter` manifest. It maps only a stable Skill
+label, its input and output contract labels, and the evidence semantics of the
+stage. It is intentionally reusable and contains no project content.
+
+```powershell
+python -m aigc_director_kit validate-local-skill-adapter `
+  examples/local_skill_adapter_case.json `
+  --json
+```
+
+The adapter is not a Skill export and does not execute a Skill. Its strict
+metadata-only field set rejects prompt bodies, paths, assets, and credentials.
+The separate [`local-skill-adapter.md`](local-skill-adapter.md) guide explains
+what may safely appear in a public manifest.
+
 ## Run the public handoff
 
 Without an action catalog, the workflow is checked structurally and action

examples/local_skill_adapter_case.json

@@ -0,0 +1,50 @@
+{
+  "contract": "aigc-director-local-skill-adapter",
+  "version": 1,
+  "adapter_id": "local-aigc-skill-bridge",
+  "visibility": "public-metadata-only",
+  "source_access": "local-only",
+  "workflow_contract": "aigc-director-skill-workflow",
+  "stages": [
+    {
+      "id": "direction",
+      "skill_label": "aigc-manga-video-director",
+      "role": "Turns direction decisions into a bounded shot-plan handoff.",
+      "input_contracts": ["project-brief", "reference-inventory"],
+      "output_contract": "aigc-director-shot-plan",
+      "evidence": "designed"
+    },
+    {
+      "id": "action-bridge",
+      "skill_label": "audio-to-prompt",
+      "role": "Turns timing and action intent into bounded action requests.",
+      "input_contracts": ["timing-and-action-intent", "shot-plan"],
+      "output_contract": "aigc-director-action-request",
+      "evidence": "inferred"
+    },
+    {
+      "id": "prompt-contract",
+      "skill_label": "prompt-optimizer",
+      "role": "Keeps reusable prompt rules separate from shot-level deltas.",
+      "input_contracts": ["shot-plan", "prompt-rules"],
+      "output_contract": "aigc-director-prompt-pack",
+      "evidence": "designed"
+    },
+    {
+      "id": "quality-evidence",
+      "skill_label": "aigc-output-qc",
+      "role": "Records evidence-bound assessment for an available artifact.",
+      "input_contracts": ["rendered-artifact", "qc-checklist"],
+      "output_contract": "aigc-director-qc-report",
+      "evidence": "observed"
+    },
+    {
+      "id": "coordination",
+      "skill_label": "aigc-project-prompt-loop",
+      "role": "Packages sanitized stage outputs into a workflow handoff.",
+      "input_contracts": ["shot-plan", "action-request", "prompt-pack", "qc-report"],
+      "output_contract": "aigc-director-skill-workflow",
+      "evidence": "designed"
+    }
+  ]
+}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aigc-director-kit"
-version = "0.2.2"
+version = "0.2.3"
 description = "CineThread: deterministic creative handoffs for AI animation, storyboards, and previs."
 readme = "README.md"
 requires-python = ">=3.10"

schemas/local-skill-adapter.v1.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:aigc-director-kit:local-skill-adapter:v1",
+  "title": "AIGC Director Local Skill Adapter v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contract",
+    "version",
+    "adapter_id",
+    "visibility",
+    "source_access",
+    "workflow_contract",
+    "stages"
+  ],
+  "properties": {
+    "contract": {"const": "aigc-director-local-skill-adapter"},
+    "version": {"const": 1},
+    "adapter_id": {"$ref": "#/$defs/label"},
+    "visibility": {"const": "public-metadata-only"},
+    "source_access": {"const": "local-only"},
+    "workflow_contract": {"const": "aigc-director-skill-workflow"},
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "items": {"$ref": "#/$defs/stage"}
+    }
+  },
+  "$defs": {
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "pattern": "^[a-z][a-z0-9-]{0,79}$"
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "skill_label",
+        "role",
+        "input_contracts",
+        "output_contract",
+        "evidence"
+      ],
+      "properties": {
+        "id": {"$ref": "#/$defs/label"},
+        "skill_label": {"$ref": "#/$defs/label"},
+        "role": {"type": "string", "minLength": 1, "maxLength": 240},
+        "input_contracts": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "uniqueItems": true,
+          "items": {"$ref": "#/$defs/label"}
+        },
+        "output_contract": {"$ref": "#/$defs/label"},
+        "evidence": {"enum": ["observed", "inferred", "designed"]}
+      }
+    }
+  }
+}

src/aigc_director_kit/__init__.py

@@ -1,6 +1,7 @@
 """CineThread public Python API."""
 
 from ._version import __version__
+from .adapter import validate_local_skill_adapter, validate_local_skill_adapter_file
 from .actions import compile_action_request, list_actions, load_action_library
 from .contract import ValidationResult, load_plan, validate_plan, validate_plan_file
 from .prompt import validate_prompt_pack, validate_prompt_pack_file
@@ -18,6 +19,8 @@
     "load_action_library",
     "load_plan",
     "run_public_example_verification",
+    "validate_local_skill_adapter",
+    "validate_local_skill_adapter_file",
     "validate_plan",
     "validate_plan_file",
     "validate_prompt_pack",

src/aigc_director_kit/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the public package version."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"