plugin-skill-ownership

harness-config skills plugins

Skill and plugin exposure rules for local harnesses. Use this page with wagents skills cleanup --dry-run and wagents skills sync --dry-run before changing any live home config, plugin cache, or skill directory.

Ownership Model

Repo-owned skills come from skills/<name>/SKILL.md. A harness should expose each repo skill through exactly one owner:

Harness	Preferred repo skill owner	Cleanup implication
Codex	Native agents@agents plugin when enabled in ~/.codex/config.toml	Do not also install repo-owned skills into ~/.codex/skills; stale plugin cache refresh stays approval-gated.
OpenCode	Direct repo path when opencode.json has skills.paths: ["skills"]	Do not add duplicate Skills CLI copies for repo-owned skills; keep runtime plugins in the repo/live plugin array.
Claude Code	Skills CLI unless a native plugin install is explicitly chosen	Repo-owned global skill copies remain valid fallback exposure.
Grok Build	Grok project/global skills plus Claude-compatible mirrored exposure	Skills CLI has no native Grok adapter; sync uses Claude Code adapter and mirrors only when requested by the sync path.
Gemini CLI, Antigravity, Crush, Cursor, GitHub Copilot	Skills CLI or platform projection surface	Keep local plugin/extension surfaces separate from repo skill copies unless a registry row declares one-owner behavior.

The normalized report fields are:

Field	Meaning
exposure_owner	The active owner class for this row, such as plugin, direct-repo-path, skills-cli, project-local, or user-local.
duplicate_class	Duplicate risk for same-name skill exposures: none, same-realpath, same-body, or divergent-body.
cleanup_action	Dry-run-only recommendation: none, remove-generated-symlink, refresh-plugin-cache, sync-home-config, preserve, or manual-review.
docs_status	Documentation coverage: documented, generated-missing, or not-applicable.

Apply boundary

wagents skills cleanup --dry-run is read-only. It may identify symlinks, stale plugin caches, or home config drift, but it does not delete files, refresh plugin caches, or write live harness configs. Those actions need a separately reviewed apply path.

Commands

Preview additive installs:

uv run wagents skills sync --dry-run

Preview duplicate cleanup and plugin drift:

uv run wagents skills cleanup --dry-run --format json

Regenerate the local reconciliation packet:

uv run python scripts/generate_harness_reconciliation.py

Use --apply only for wagents skills sync after reviewing the dry-run output. wagents skills cleanup --apply intentionally exits until a reviewed apply manifest exists.

Apply continue-on-error

wagents skills sync --apply runs every planned Skills CLI batch for the selected harnesses before exiting. A failed batch does not stop later batches from running. When any batch fails, the command exits non-zero and machine-readable output includes an apply_failures array:

{
  "ok": false,
  "mode": "apply",
  "apply_failures": [
    {
      "argv": ["npx", "skills", "add", "..."],
      "returncode": 1,
      "text": "npx skills add ..."
    }
  ]
}

Preview the full plan first with wagents skills sync --dry-run --format json.

Installed supersession aliases

Stale one-off installed skill ids that were renamed upstream are listed in config/skill-installed-supersession.json. When --include-installed is set and the verified catalog already owns the replacement id, sync skips the stale installed row instead of treating it as missing.

Duplicate Classes

Class	Interpretation	Default action
none	Only one exposure for that skill name was found.	No cleanup.
same-realpath	Multiple harness entries point to the same resolved skill directory.	Keep only when that owner is expected; remove generated repo symlinks when a plugin/direct path owns exposure.
same-body	Multiple directories have identical SKILL.md content.	Preserve unless the row is repo-owned and superseded by plugin/direct-path ownership.
divergent-body	Same skill name resolves to different SKILL.md content.	Manual review before any install, deletion, or promotion.

Plugin Surfaces

Native and runtime plugins are documented through the harness config docs and the plugin/extension registry:

Surface	Source	Documentation responsibility
Claude Code plugin	.claude-plugin/plugin.json, .claude-plugin/marketplace.json	Repo-owned native plugin manifest, documented here and in AGENTS.md.
Codex plugin	.codex-plugin/plugin.json, .agents/plugins/marketplace.json	Repo-owned native plugin manifest; cache refresh is a cleanup recommendation, not an automatic action.
OpenCode runtime plugins	opencode.json, live ~/.config/opencode/opencode.json, TUI ~/.config/opencode/tui.json	Repo plugin array uses @latest; live-only or TUI-only plugins are preserved as user-local unless promoted.
Gemini extensions	~/.gemini/extensions, ~/.gemini/settings.json	Local extension rows are preserved unless a registry or catalog entry promotes them.
Chrome DevTools upstream plugin/extension	config/plugin-extension-registry.json, MCP registry ownership rules	Plugin/extension owners suppress duplicate standalone MCP projection for that harness.

Skill Documentation

Custom skills are documented from the repo-owned skill catalog path:

• Source skill body: skills/<name>/SKILL.md
• Human catalog entry: docs/src/authoring/skills/<name>.mdx
• Generated public page: /skills/catalog/custom/<name>/
• Generated machine index: docs/public/generated-registries/skills-catalog-index.json

Curated external skills stay out of skills/ and are documented in the authoring catalog:

• Human catalog entry: docs/src/authoring/skills/<name>.mdx
• Public generated page: /skills/catalog/external/<name>/
• Install hub: /skills/catalog/external/
• Sync source: wagents skills sync --dry-run

Included third-party plugin or extension skills must be documented in the owning registry or catalog entry before promotion. If a duplicate local exposure has no trusted provenance or docs entry, keep it user-local and use manual-review or preserve, not automatic install or deletion.

Related

sync-manifestProjection ownership ledger for generated, merged, copied, and symlinked harness surfaces.

mcp-registryMCP one-owner rules, including plugin and extension ownership.

Skills CatalogGenerated catalog for repo-owned custom and curated external skills.

External SkillsCurated external install hub and trust-gate workflow.