Agent Skill Management

Use agent-marketplace/ for the portable source/build project. Its root owns the
single apm.yml, lock, and committed apm_modules/; packages/ defines separate
plugins with their own selections, authored content, and native metadata. Host activation
policy lives in home/.chezmoidata/agent_plugins.toml. Native clients own their
install records and caches; ~/.agents/plugins is the shared materialized
artifact.

1. Choose the working surface. Read the
   project workflow for authored skills,
   APM acquisition, selections, patches, versions, and export. Read
   materialization for chezmoi or artifact
   copy changes, and reconciliation for native
   installation, enablement, or rollback.
2. Change durable inputs. Edit authored skills/ directly and imported content
   through patches or overlays. Keep the shared cache pristine. Bump only the
   affected plugin's .codex-plugin/plugin.json version; the build derives its
   APM publication manifest and removes it after generating native metadata. The console plans
   imported edits as patches, stages paired invocation controls and native
   version bumps, then builds the staged result before guarded writes. Imported
   description/frontmatter edits fingerprint the whole marketplace source before
   planning and recheck it before writing any file. If those inputs change,
   re-plan and revalidate; --allow-dirty-targets does not bypass that check.
   Deleting a root dependency requires checking every plugin's skill and
   supporting-payload selections, including disabled plugins.
3. Validate the changed boundary. Run just -f agent-marketplace/justfile -d agent-marketplace check
   for package changes; run just test-python -p test_packages.py -p 'test_console_*.py' for
   consumer or console changes. Activation changes also need the Claude, Codex,
   Cursor, and pi config merge checks. Native client changes need
   just test-agent-skill-packages-native on a host with both clients installed.
   The consumer suite applies scripts 35/36, config entries, and managed symlinks
   together in an isolated home, then repeats apply and verifies managed targets.
   Completion means the relevant checks pass and every payload change has a
   matching native version bump.
4. Materialize and reconcile within the user's requested apply scope. Read
   the current reference for
   paths and commands. Keep the previous artifact until native inventories and
   enabled states are verified. Source changes alone do not reload an existing
   agent session.

For input recovery, restore missing committed files from Git or a complete source
export. Acquisition refuses unaccepted cache/lock changes; it is not the repair
command for a deleted committed helper. Keep disposable probes in ignored scratch
and record useful evidence in research docs.

A human-only skill needs both disable-model-invocation: true and the Codex
sidecar's policy.allow_implicit_invocation: false. The build validates the pair.
Every published skill directory must retain its root SKILL.md, including after
patches and overlays. Python __pycache__ entries are ignored without traversal
and never enter the artifact; other payload symlinks are rejected.
Keep all Codex interface metadata; hook-bearing packages retain hooks: {} under
the current skills-only Codex policy.

Runtime inventory comes from native catalogs and selected built payloads. Treat
agent-marketplace/apm.lock.yaml as the upstream identity/revision source. Preserve upstream license
and notice files in the published plugin as well as the cache. Subdirectory
imports need explicit root-notice payload selections when those texts are absent
from the selected tree; see the project workflow. Generate no SOURCE.md or
replacement per-skill provenance store.

For acquisition edge cases, read third-party imports.
For package shapes, read package layout.
The test index distinguishes the
ordinary checks from native host checks, console producer parity, and authenticated
evals. Those lanes establish different guarantees.