Maintain Agent Plugins

Maintain Agent Plugins

Purpose

Create and maintain Codex plugin source without reintroducing hand-maintained metadata, per-plugin commands, Python automation, or customizable scaffolding. Use current official OpenAI plugin documentation for host schema facts, then apply the fixed Socket repository policy through the managed runtime.

Required Interface

Plugin maintenance has exactly two public commands. Each processes every plugin manifest and marketplace entry owned by the repository:

just plugins-check
just plugins-apply

Do not add per-plugin, per-manifest, scaffold, sync, bootstrap, or alternate mode recipes. plugins-check is read-only. plugins-apply performs the complete deterministic reconciliation and then checks its result.

Installation

1. Confirm the target is a Git repository root.
2. Run scripts/maintain-agent-plugins.fsx --repo-root <path> --operation install from this skill once to copy the managed runtime and Just import.
3. The installer also adds ordered repository-maintenance hooks when the target already uses the canonical scripts/repo-maintenance/ runtime.
4. Run just plugins-apply, then just repo-validate when repository-skills is present.

Use --operation refresh to replace managed files from this skill and --operation report-only for a read-only drift report. These installer modes are skill internals, not additional Just tasks.

Fixed Policy

• Publisher: Gale, mail@galewilliams.com, https://github.com/gaelic-ghost.
• License: Apache-2.0.
• Plugin names: stable kebab case matching their directory.
• Manifest: .codex-plugin/plugin.json; bundled skills: ./skills/.
• Default plugin repository URL: https://github.com/gaelic-ghost/<plugin-name>.
• Local marketplace policy: AVAILABLE and ON_INSTALL.
• Default category: Developer Tools unless the plugin already has an intentional product category.
• Default-discovered hook files stay at hooks/hooks.json; do not duplicate that default path in the manifest.
• interface.defaultPrompt is an array of at most three concise prompts.

The runtime owns these choices. Do not add user profiles, policy files, template variables, interactive questions, or project-local overrides.

Creating a Plugin

1. Establish one bounded capability and its owning plugin name.
2. Create the plugin directory, .codex-plugin/plugin.json, AGENTS.md, and at least one complete skill under skills/<skill-name>/SKILL.md.
3. Add only real optional surfaces: .mcp.json, .app.json, hooks/, agents, or assets must have an actual consumer and validation path.
4. Use the fixed publisher and license policy. Write plugin-specific purpose, descriptions, prompts, keywords, and capability content directly; these are authored semantics, not customization inputs.
5. Run just plugins-apply. In Socket, this adds missing root marketplace wiring and checks the complete plugin set.
6. Run only the repository root integration/E2E path. Do not create tests under the plugin or skill.

Ownership Handoffs

• Use repository-skills:maintain-project-repo for the four canonical docs, repo-wide synchronization and validation, protected-main releases, and version changes.
• Use agent-engineering-skills for agent orchestration, automation, eval, and scheduling behavior.
• Use agent-portability-skills for ACP, A2A, MCP boundary selection, Zed, Hermes, and other host adapters.
• Keep runtime hooks and MCP implementation with the plugin that ships them; this skill owns their packaging consistency, not their product behavior.

Guards

• Never edit installed plugin caches or enabled-state configuration.
• Never restore bootstrap-skills-plugin-repo, sync-skills-repo-guidance, Python generators, or nested plugin tests.
• Never infer a new packaging layer or publish destination.
• Stop when a manifest name and directory disagree, a managed target is not a regular file, or a required optional asset is missing.

Script Inventory

• scripts/maintain-agent-plugins.fsx