docs: add public contributor development skills

.agents/skills/cli-guide/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: cli-guide
+description: Navigate and change the MiniMax Code command tree, interactive TUI, headless exec, ACP adapters, or their in-process runtime connection. Use when implementing or debugging CLI behavior in this repository.
+---
+
+# CLI Architecture Guide
+
+Read `docs/architecture.md` and the current command registration before proposing
+a change. The standalone entry point lives in `packages/tui`.
+
+## Entry points
+
+| Path | Responsibility |
+| --- | --- |
+| `packages/tui/src/index.ts` | Process bootstrap and runtime environment |
+| `packages/tui/src/cli/main.ts` | Command execution and process lifecycle |
+| `packages/tui/src/cli/program.ts` | Commander command registration |
+| `packages/tui/src/cli/contract.ts` | Interactive and exec option contracts |
+| `packages/tui/src/tui/` | Interactive terminal UI |
+| `packages/tui/src/headless/` | Exec invocation, output, cancellation and settlement |
+| `packages/tui/src/acp/` | ACP protocol adapter |
+| `packages/tui/src/runtime/adapter.ts` | Adapter to the in-process CliService |
+| `packages/local-runtime-v2/src/local/` | Local product service entry points |
+| `packages/protocol/src/local.ts` | Shared CLI data structures |
+
+The execution path is:
+
+```text
+TUI / exec / ACP
+  -> CliService
+  -> local applications
+  -> session / turn / agent services
+  -> model providers and tools
+```
+
+Preserve that in-process boundary. Shared behavior belongs in the relevant
+application or service; presentation and transport behavior belong in their
+adapters. Trace callers before assuming a fix to one adapter covers the others.
+
+## Implementing changes
+
+- For commands and flags, inspect `cli/program.ts`, `cli/contract.ts`, and the
+  affected command handler together. Check parsing, help, dispatch and errors.
+- For interactive behavior, follow the controller and rendering path under
+  `tui/`. Check session selection, queued input and interruption where affected.
+- For exec, follow invocation through output and settlement. Verify stdout,
+  stderr, exit code and cancellation; help output alone is insufficient.
+- For ACP, check protocol updates and the underlying runtime operation together.
+- For shared runtime changes, identify all affected TUI, exec and ACP consumers.
+
+## Verification
+
+Use [testing-workflow](../testing-workflow/SKILL.md) to select declared tests.
+Build the standalone artifact before inspecting its actual help:
+
+```bash
+pnpm build
+node dist/cli.js --help
+node dist/cli.js exec --help
+node dist/cli.js acp --help
+```
+
+Read current help before documenting flags. Use temporary data directories and
+synthetic inputs for behavior checks, following the existing smoke/BYOK tests.
+Report offline protocol tests separately from live-provider acceptance.

.agents/skills/cross-layer-drift-sweep/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: cross-layer-drift-sweep
+description: Check completed cross-layer changes for stale fields, defaults, types, contracts or wording across storage, runtime, adapters, TUI and documentation. Use after a rename or contract change with downstream consumers, not for unrelated single-file edits.
+---
+
+# Cross-Layer Drift Sweep
+
+Type checking can miss manual mappings, serialized fields and assertions hidden
+behind casts. Sweep the narrow data flow affected by the change before reporting
+completion.
+
+## Establish the change
+
+Record the change axis: type narrowing, field rename, configuration default,
+contract evolution or display wording. Name the old and new expressions and the
+producer and final observable consumer.
+
+Draw the relevant flow, for example:
+
+```text
+storage -> runtime writer -> local service -> adapter -> TUI / exec / ACP -> docs
+```
+
+Only include layers that actually consume the changed value.
+
+## Sweep
+
+1. Search both old and new expressions. Include source, comments, tests,
+   fixtures, snapshots and relevant documentation. Paired searches reveal layers
+   that adopted only part of a change.
+2. Check the likely gaps for the change axis:
+
+   | Axis | Common gaps |
+   | --- | --- |
+   | Type narrowing | Runtime writers, filesystem reads with casts, serializers, adapter mappings |
+   | Field rename | Schema, migrations, inline test DDL, fixtures, mappings, user-visible labels |
+   | Configuration default | Defaults, thresholds, examples, logs, status output and documentation |
+   | Contract evolution | Local protocol types, service exports, call sites and compatibility fixtures |
+   | Display wording | TUI, exec output, logs, screenshots and exact-string assertions |
+
+3. Fix mismatches within the changed data flow. Explain deliberate compatibility
+   remnants in an adjacent comment or regression test. Avoid changing unrelated
+   matches merely because they contain the same token.
+4. Verify an assertion at the final observable layer, such as rendered text,
+   serialized output, a local-service result or a database-backed read. Reuse an
+   existing assertion when it already covers the behavior; add one when there is
+   a meaningful regression gap.
+5. Run affected tests and type checks using
+   [testing-workflow](../testing-workflow/SKILL.md). For runtime inputs with
+   alternate paths or caches, also use
+   [verify-all-runtime-sinks](../verify-all-runtime-sinks/SKILL.md).
+
+## Evidence
+
+Report the axis, data flow, old/new search terms, layers checked, mismatches fixed
+and verification results. Explain remaining old-token matches. If the final
+consumer could not be exercised, state the gap and the nearest contract evidence
+instead of treating a parser-only test as complete validation.

.agents/skills/retro/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: retro
+description: Extract evidence-backed lessons from a completed development session and propose focused improvements to repository guidance. Use when the user asks for a retrospective or to capture reusable lessons.
+---
+
+# Session Retrospective
+
+Turn concrete failures, retries and workflow gaps into a small set of reusable
+improvements. Do not turn one-off preferences into repository-wide rules.
+
+## Review the evidence
+
+For each useful lesson, record:
+
+- **Event:** what happened, with a public-safe file, command, error or commit.
+- **Cause:** the demonstrated reason, separated from hypotheses.
+- **Lesson:** what a future contributor should do differently.
+- **Impact:** safety/data, correctness, efficiency or preference.
+
+Skip unsupported opinions and one-off circumstances. Combine duplicate lessons
+and keep the result focused on the few changes that would prevent recurrence.
+Redact credentials, private service details and real user content from evidence.
+
+## Find the right home
+
+Read existing guidance before proposing additions:
+
+| Lesson | Candidate location |
+| --- | --- |
+| Repository-wide constraint | `AGENTS.md` or `CONTRIBUTING.md` |
+| A specific reusable workflow | The relevant `.agents/skills` entry |
+| Build, release or source-sync procedure | The relevant document under `docs/` |
+| A behavioral defect | A focused code fix and regression test proposal |
+
+Prefer correcting an existing instruction over introducing a parallel process
+or a new notes/proposals directory. Check current source and scripts before
+preserving an explanation that might already be stale.
+
+## Scope and delivery
+
+If the user asks only for a retrospective, return the findings and proposed
+edits. Apply documentation changes when requested, within the established scope.
+Do not treat the retrospective as authorization to create issues, send messages,
+publish changes or modify personal/agent memory. Write memory only when the user
+explicitly asks for that persistence and the environment supports it.
+
+For applied changes, keep public contributor guidance in English. New files
+require publication review and inventory regeneration; content-only changes do
+not. Report the lessons, evidence, proposed or applied destinations, checks run
+and remaining decisions.

.agents/skills/testing-workflow/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: testing-workflow
+description: Select and report verification for MiniMax Code changes using the repository's declared test suites and CI gates. Use when validating code, skills, documentation, build tooling or source-distribution changes.
+---
+
+# Testing Workflow
+
+Start with changed files, then identify the owning runtime, user entry point and
+final observable behavior. Read `AGENTS.md`, `CONTRIBUTING.md` and the applicable
+steps in `scripts/verify.mjs`.
+
+## Focused iteration
+
+Vitest files belong to groups in `test/vitest-suites.json`; aliases and inclusion
+come from `vitest.oss.config.mjs`. Select an existing declared file for a focused
+run, for example:
+
+```bash
+pnpm exec vitest run --config vitest.oss.config.mjs packages/tui/test/unit/headless-contract.test.ts
+```
+
+Register new Vitest files in the suite declaration. Do not add hard-coded file
+lists to package scripts or the Vitest configuration. Vendored upstream test
+suites are outside this distribution's verification.
+
+| Scope | Repository gate |
+| --- | --- |
+| Runtime, TUI, providers, plugins and ACP | `pnpm test:capabilities` |
+| Headless CLI and offline BYOK behavior | `pnpm test:byok` |
+| CLI artifact smoke | `pnpm test:smoke` |
+| Public artifact content | `pnpm test:artifact` |
+| TUI build-mode contract | `pnpm test:status-contract` |
+| Permission facade on macOS/Linux | `pnpm test:policy` |
+| Sandbox on macOS | `pnpm test:sandbox` |
+| Source-sync, workflow and release tools | `pnpm test:release-tools` |
+| Types and standalone build boundary | `pnpm typecheck`, `pnpm build`, `pnpm check:standalone` |
+| Published files and generated paths | `pnpm check:source`, `pnpm check:tsconfig` |
+
+Artifact-dependent tests require a current `pnpm build`. Keep test state and
+reports outside the repository, using synthetic data and temporary directories.
+
+## Delivery verification
+
+Run `git diff --check` and the relevant individual gates while editing. Review
+new or removed files before regenerating `release/public-source.json` with
+`node scripts/source-inventory.mjs --write`.
+
+Before opening a PR, run `pnpm verify` on the reviewed commit with a clean tracked
+working tree. Source export reads committed HEAD and rejects uncommitted tracked
+changes; report that limitation if only iteration checks are possible.
+
+Use `pnpm verify --list` to inspect the current platform's gates. Use the `docs`
+profile only when every changed path qualifies under `scripts/ci-changes.mjs`.
+Skills under `.agents/skills`, unknown paths and inventory changes require the
+full profile. The `archive` profile is for source-archive validation, not a way to
+bypass the clean-commit export requirement.
+
+## Manual evidence and reporting
+
+For CLI behavior, exercise the built `dist/cli.js` and inspect stdout, stderr and
+exit code. For terminal presentation, exercise the relevant interaction when
+feasible. For provider or service changes, distinguish offline fixtures from a
+real endpoint call.
+
+Report scope, commands and results, manual scenarios, and untested boundaries.
+Use PASS/FAIL/BLOCKED for actual checks; mark checks that did not run explicitly.
+Local macOS success does not establish Windows/Linux or live-service acceptance.

.agents/skills/verify-all-runtime-sinks/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: verify-all-runtime-sinks
+description: Verify that runtime-affecting schema, prompt, identity, adapter, cache or rename changes reach every affected consumer. Use before declaring runtime validation complete when alternate entry points or persisted/generated values can retain old behavior.
+---
+
+# Verify All Runtime Sinks
+
+Identify where a changed value is finally consumed, beyond its first parser or
+happy-path test. This skill defines where to verify; use
+[testing-workflow](../testing-workflow/SKILL.md) for commands and gates.
+
+## Procedure
+
+1. Name the changed contract, field, prompt, identity or adapter behavior. Identify
+   the producer and final runtime consumer, and describe the stale behavior that
+   a partial change would leave behind.
+2. Map the affected consumers. Mark each dimension `covered`, `not applicable`
+   or `unknown`, with a reason:
+   - **Parser to runtime:** normalized objects, managers, launch options,
+     serialization boundaries and service inputs.
+   - **Alternate entry points:** TUI, exec, ACP, task/session launches, built-in
+     and project agents, and explicit historical-data importers where relevant.
+   - **Generated or cached values:** bundled prompts, static prompt caches,
+     compiled configuration, persisted state and memoized objects.
+   - **Fixtures and artifacts:** tests, snapshots, example agents/skills and
+     built distribution assets when affected.
+   - **String remnants:** old property names, environment/configuration keys,
+     log labels and documentation used by generation or tests.
+3. Search for both old and new tokens beyond source files. Include ignored build
+   outputs explicitly when checking artifacts; an ordinary repository search may
+   skip them. Inspect raw serialized shapes where types or casts can hide drift.
+4. Exercise the affected runtime paths through their final consumers. Check each
+   adapter that can bypass the tested path. Shared implementation is evidence
+   only after tracing how those adapters reach it. For prompts, check source
+   selection and caching; for identity/schema changes, check agent kinds that
+   parse differently.
+5. Record commands, results, remaining old-token hits and compatibility reasons.
+   Inspect or regenerate caches using isolated test state; do not clear a user's
+   sessions or configuration as part of verification.
+
+## Completion bar
+
+Do not declare complete runtime coverage while a relevant consumer is `unknown`
+or an unexplained old value remains. Report narrower passing checks and the
+remaining gap. Parser tests alone do not establish propagation through launch,
+execution and final presentation.
+
+Example evidence:
+
+```text
+Parser to service: covered by the affected integration test.
+Exec and ACP: covered by adapter tests; interactive TUI: not run.
+Prompt cache: not applicable; the changed value is not cached.
+Old field: retained only in the historical importer and its fixture.
+Result: focused checks pass; interactive acceptance remains unverified.
+```

CONTRIBUTING.md

@@ -18,6 +18,20 @@ Preserve original third-party license text. Localized product strings, multiling
 
 ## Local validation
 
+Repository development skills are available under [`.agents/skills`](.agents/skills):
+
+| Skill | Use |
+| --- | --- |
+| [cli-guide](.agents/skills/cli-guide/SKILL.md) | Navigate TUI, exec, ACP and their runtime boundary |
+| [cross-layer-drift-sweep](.agents/skills/cross-layer-drift-sweep/SKILL.md) | Check renames, defaults and contracts across consumers |
+| [testing-workflow](.agents/skills/testing-workflow/SKILL.md) | Select focused checks and the required delivery gates |
+| [verify-all-runtime-sinks](.agents/skills/verify-all-runtime-sinks/SKILL.md) | Verify alternate runtime paths, caches and artifacts |
+| [retro](.agents/skills/retro/SKILL.md) | Turn demonstrated failures into focused guidance improvements |
+
+These are contributor workflows, separate from bundled product skills. They are
+adapted to this distribution's paths and verification contracts; workflow changes
+should update the relevant skill alongside its source of truth.
+
 ```bash
 pnpm install --frozen-lockfile
 pnpm verify