bootstrap-skills-plugin-repo

Bootstrap Skills Plugin Repo

Bootstrap or align a source-first Agent Skills repository.

This is the Codex-ready bootstrap workflow inside Agent Portability Skills. Use it for the shared skills repository shape first, then hand off to future host-adapter workflows when a target such as Zed Agent, Xcode, OpenCode, or Claude Code needs additional package or config decisions.

Codex Model Note

State plainly that OpenAI's documented Codex plugin system exposes repo-visible plugins through marketplace catalogs and does not document a richer repo-private scoping model beyond that. This repository pattern allows root .codex-plugin packaging. Do not normalize nested staged plugin directories or installer-era helper workflows for this repo family.

Before adding detailed guidance about Codex Plugins, Skills, MCP, Hooks, marketplaces, or subagents, refresh the relevant OpenAI Codex docs. Keep generated repo guidance focused on durable local policy and link to the official docs for details that can drift.

Codex Plugin Root Structure

When bootstrapping or aligning a plugin repo, follow the current OpenAI plugin structure:

• every plugin has a manifest at .codex-plugin/plugin.json
• only plugin.json belongs in .codex-plugin/
• skills/, .app.json, .mcp.json, hooks/, and assets/ belong at the plugin root
• plugin manifests should point to bundled skill folders with "skills": "./skills/"
• plugin manifests may point to bundled lifecycle hooks with "hooks": "./hooks/hooks.json"; if hooks live at ./hooks/hooks.json, Codex checks that default path automatically
• plugin-bundled hooks are non-managed hooks, so installing or enabling a plugin does not make those hooks trusted automatically
• marketplace source.path should point at the plugin root directory

Dependency Provenance

When creating or aligning AGENTS.md, include strict dependency guidance:

• shared project dependencies must resolve from GitHub repository URLs, package managers, package registries, or other real remote repositories
• committed dependency declarations, lockfiles, scripts, docs, examples, generated project files, and CI config must not point at machine-local paths
• machine-local dependency paths are expressly prohibited in any project that is public or intended to be shared publicly

Codex Subagent Guidance

For existing repositories that need broad guidance drift discovery before edits, prefer sync-skills-repo-guidance and its skills-repo-guidance-sync custom-agent role. For Socket-wide docs, marketplace, or proposal planning, run Socket Steward first when its deterministic audits fit the question. Use this bootstrap skill for new repository structure or structural alignment after the main thread has reviewed any audit or subagent findings.

When creating or aligning skills that can benefit from parallel support work, add optional Codex Subagent Fit guidance that matches OpenAI's current Codex subagent docs:

• Current Codex releases enable subagent workflows by default, but Codex only spawns subagents when there is an explicit trigger: the user asks for subagents or parallel agent work, or a narrower skill/plugin workflow instructs the agent to ask first and the user grants explicit permission.
• Built-in agents include default, worker, and explorer; mention project-scoped custom agents under .codex/agents/ only when the repo intentionally owns agent configuration.
• Good fits are bounded read-heavy discovery, docs pulling, tests, triage, log analysis, and summarization.
• Subagents should return concise findings, evidence, links, or file references instead of raw intermediate output.
• Apply-mode or implementation edits should stay in the main thread unless the user explicitly asks for parallel implementation and each worker has a disjoint write scope.
• Plugin-specific guidance can be stricter. For example, Codex Security repository-wide scans may require asking for subagent use because the scan quality depends on parallel file-pass review.

Do not add subagent guidance to every skill by default. Use docs/maintainers/codex-subagent-skill-guidance.md to decide whether the target skill has real parallelizable support work.

Codex Install Guidance

Bootstrap docs should make the Git-backed marketplace path the default user install/update story:

codex plugin marketplace add <owner>/<repo>
codex plugin marketplace upgrade <marketplace-name>

Use explicit refs such as <owner>/<repo>@vX.Y.Z only for pinned reproducible installs. Use manual local marketplace or copied-payload instructions only for local development, unpublished testing, or fallback cases.

Keep discovery mirrors, plugin packaging, marketplace catalogs, plugin payload directories, installed cache paths, and config-state separate. Do not blur "where Codex can see a plugin", "where the plugin payload lives", "how Codex updates the marketplace", and "whether the plugin is enabled" into one sentence.

If you mention project-scoped .codex/config.toml, describe it as a general Codex config surface from the config reference, not as a separate documented plugin install surface.

GitHub Repository Settings

When the bootstrapped repository has a GitHub remote, use productivity-skills:maintain-github-repository to audit or apply the current recommended GitHub repository settings. Keep local structure bootstrap separate from server-side settings mutation, keep visibility changes approval-gated, and preserve any documented maintainer direct-push workflow.

The GitHub settings pass should cover repository features, merge modes, Dependabot and security settings, private vulnerability reporting for public repos, web commit sign-off when DCO applies, and branch protection that requires the actual CI check context without requiring unavailable reviewers.