Plugin Autopilot

View saved version →

---
name: agentic-repo-discovery
description: Use when an existing repository contains agents, prompts, workflows, playbooks, commands, or Skills and you need to identify which capabilities are worth converting into a ChatGPT/Codex Plugin.
---

# Agentic Repo Discovery

Find the reusable user workflows inside a repository before creating Plugin files.

## Procedure

1. Read repository instructions and the main README first.
2. Run the bundled analyzer when filesystem execution is available:

```bash
python3 ../chatgpt-codex-plugin-autopilot/scripts/analyze_repo.py <target-repo> --json
```

3. Inspect high-scoring candidates in context. The analyzer finds signals; it does not understand the full product by itself.
4. Build a candidate disposition table using: `preserve_skill`, `compile_skill`, `reference_only`, `runtime_dependency`, `internal_only`, or `discard`.
5. Identify the user's repeatable job for every candidate. Reject candidates whose only value is repository maintenance trivia unless that is the intended Plugin product.
6. Flag secrets, organization-specific instructions, destructive operations, security-sensitive workflows, hidden telemetry, and policy-sensitive capabilities for explicit public-distribution review.
7. Recommend `skills-only`, `MCP-backed`, or `hybrid` from actual behavior. Treat `.mcp.json` or `.app.json` as evidence to inspect, not automatic proof that the public Plugin needs them.
8. Hand selected workflow candidates to `workflow-to-skill-compiler` and the overall product boundary to `plugin-experience-architect`.

## Output

Return a concise conversion brief containing:

- repository/ref inspected
- reusable jobs discovered
- candidate dispositions with reasons
- architecture recommendation with confidence
- runtime dependencies
- public exclusions
- missing evidence
- next conversion actions

Do not generate Plugin configuration before this boundary is clear.

View saved version →

---
name: chatgpt-codex-plugin-autopilot
description: Use when converting an agentic repository into a ChatGPT/Codex Plugin or when building, repairing, validating, packaging, submitting, publishing, or auditing an existing Plugin.
---

# ChatGPT/Codex Plugin Autopilot

Take an arbitrary repository from agentic-workflow discovery to a verified ChatGPT/Codex Plugin artifact and, when explicitly authorized, through release/submission. This repository is itself a ChatGPT/Codex Plugin and must remain capable of validating and packaging its own installed surface.

Treat the target repository as authoritative for product behavior and release channels. Never require Riqor, Bun, Node, or a project-specific layout unless the target already requires it.

## Operating contract

1. Verify the current **official OpenAI Plugin** and Skill documentation before editing public configuration. Current official docs override remembered schema, examples, limits, and tool availability. Read `references/official-contract.md`, `references/branding-and-listing.md`, `references/host-python-sandbox.md`, and `references/host-workspace-capabilities.md`.
2. Inspect repository instructions, package metadata, manifests, Skills, agents, workflows, MCP/app configuration, hooks, assets, legal/support pages, CI, release scripts, tags, and public-distribution constraints before changing anything.
3. When the repository is not already a coherent Plugin, run Repo-to-Plugin conversion first. Use `scripts/analyze_repo.py` plus `agentic-repo-discovery` to identify candidate workflows and set the public boundary.
4. Classify the target as `skills-only`, `MCP-backed`, or `hybrid` from declared active components and actual user behavior, not from stray `.app.json` or `.mcp.json` files.
5. Run the **public-distribution safety** review before mirroring internal capabilities into public Skills.
6. Compile selected workflows with `workflow-to-skill-compiler`. Preserve decisions, approvals, tests, evidence, and stop conditions.
7. Build the host-workspace capability profile with `plugin-experience-architect`. Decide whether the Plugin needs read, list, search, grep, write, patch, shell, and Python. Keep read-only discovery separate from mutation operations.
8. For Plugins that interact with files, repositories, generated artifacts, or workspace state, install the canonical `host-workspace-operator` Skill with `scripts/install_host_workspace_skill.py`. Do not overwrite a customized existing copy without review.
9. When deterministic computation, parsing, hashing, archive inspection, or Python-based verification is useful, include and invoke `sandbox-python-executor`. In ChatGPT, explicitly use the **python tool** when it is available. Do not claim execution without execution evidence.
10. Build or repair `.codex-plugin/plugin.json`, focused Skills, optional `agents/openai.yaml`, optional MCP/app configuration, optional hooks, square branding, and accurate public URLs.
11. For public preparation, require the product-specific SVG brand pack from `plugin-brand-identity-designer`: `assets/logo-light.svg`, `assets/logo-dark.svg`, and a compact square icon.
12. Build truthful public metadata through `plugin-directory-listing-writer`: Name, Subtitle, Description, Category, verified Developer name, Website, Customer support, Privacy policy, Terms, Version, Package name, Capabilities, starter prompts, and reviewer material.
13. Enforce package shape before copy polish. Only `plugin.json` belongs inside `.codex-plugin/`; every intended Skill is an immediate real child directory of `skills/` containing `SKILL.md`.
14. Validate declared paths and assets. Reject outer whitespace, control characters, absolute paths, drive paths, `..` traversal, package escapes, missing files, invalid square branding, secret-shaped files, transient bytecode, and symlinks.
15. Validate `agents/openai.yaml` when present as fail-closed YAML with the documented mapping/string/boolean/list types. Do not invent dependencies for host-native read/write/search/grep/shell/patch/Python capabilities. Documented Skill dependencies remain limited to the current official contract.
16. Treat `.app.json` and `.mcp.json` as active only when the manifest declares the matching component.
17. Run repository-native tests plus `scripts/validate_plugin.py` and fail closed on blocking errors. When the host provides execution tools, **execute the checks**; do not merely print commands and describe them as verified.
18. Build the ZIP twice with `scripts/package_plugin.py` and require deterministic byte identity or matching SHA256. Extract a fresh copy and validate it again.
19. Inspect archive contents, excluded capabilities, secret/privacy boundaries, package-relative paths, installation behavior, and generated workspace Skills.
20. Smoke a fresh install on every available ChatGPT/Codex surface. Do not claim unavailable surfaces were tested.
21. Run the separate submission-readiness gate. A valid ZIP, logo, listing, or successful local install is not OpenAI approval.
22. Diagnose uploader/review failures from the current official docs and `references/submission-errors.md`; fix root causes and rerun the entire gate.
23. Under **Full Autopilot Publish**, commit, tag, push, publish, and create releases without another routine confirmation only after all gates pass and only within the user's authorized release scope.
24. Report exact commit, tag, version, hashes, executed tests, skipped checks, remote status, and residual warnings.

## Repo-to-Plugin conversion mode

### Stage A: discover

Run:

```bash
python3 <autopilot-skill>/scripts/analyze_repo.py <target-repo> --json
```

Use `agentic-repo-discovery` to assign each candidate one disposition:

```text
preserve_skill
compile_skill
reference_only
runtime_dependency
internal_only
discard
```

Do not treat discovery as automatic publication.

### Stage B: compile workflows

Use `workflow-to-skill-compiler`. One source file does not have to become one Skill. Merge fragments serving one job, split mixed workflows, and keep private or unsafe capabilities out of the public package.

When a workflow touches local files or code, express its operations using host capabilities rather than one hard-coded tool implementation.

### Stage C: design the Plugin experience

Use `plugin-experience-architect` to define:

- primary user and recurring job
- public Skill set and exclusions
- required/optional app dependencies
- capability language and starter prompts
- invocation boundaries
- host-workspace capability profile
- mutation boundary
- whether `host-workspace-operator` should be installed
- whether `sandbox-python-executor` is needed

### Stage D: install the host workspace baseline

For repository/file-oriented Plugins, run:

```bash
python3 <autopilot-skill>/scripts/install_host_workspace_skill.py <target-plugin>
```

The generated Plugin receives a portable Skill covering:

```text
read
list
search
grep
write
patch
shell
python
```

These are host-native capabilities, not permissions granted by the Plugin. The Skill maps intent to whichever compatible tools the current ChatGPT/Codex host exposes.

Default behavior:

- read/list/search/grep first for discovery
- patch before broad rewrite when available
- write only for authorized mutation
- shell for repository commands when narrower tools are insufficient
- Python for deterministic computation and verification
- no fabricated tool use when a capability is unavailable

The installer is idempotent and refuses to overwrite a customized existing `host-workspace-operator`.

### Stage E: execute in the host sandbox

Use `sandbox-python-executor` when a claim depends on real local computation, package inspection, hashing, file transformation, or the bundled Python validators/packagers.

In ChatGPT, when the **python tool** is available, use it. In Codex, use the safe host execution environment available to the session. Preserve execution evidence such as status, important output, generated file paths, and hashes.

If the required tool is unavailable, state that limitation and keep execution-dependent claims unverified.

### Stage F: design the brand identity

Use `plugin-brand-identity-designer` after the product boundary is stable. Create product-specific light/dark SVG variants sharing one geometry plus a small icon. Do not invent unsupported manifest fields for extra variants.

### Stage G: build the Plugin Directory listing

Use `plugin-directory-listing-writer`, then run:

```bash
python3 <autopilot-skill>/scripts/build_directory_pack.py <target-plugin> --json
```

Missing verified publisher/legal information is a blocker, not a copywriting opportunity.

### Stage H: prove and prepare submission

Run package preflight, deterministic packaging, clean extraction validation, reviewer tests, and discovery checks. Only then use `submission-pack-builder`.

Keep these states separate:

```text
analyzed
conversion planned
workspace ready
brand ready
listing ready
locally validated
submission ready
submitted
approved
published
```

## Host workspace operations rule

`host-workspace-operator` is the shared execution policy for local workspace work.

Use the narrowest available capability:

- `read`: known file/range
- `list`: directory/workspace shape
- `search`: broad or semantic discovery
- `grep`: exact text, regex, symbol, or field lookup
- `patch`: focused existing-file edit
- `write`: create/replace content when authorized
- `shell`: tests, git, archive, or repository commands
- `python`: deterministic parsing, transformations, hashes, and validation

Read-only operations should establish the current state before mutations. Write, patch, delete, move, rename, formatting changes, and mutating shell commands are state changes and must respect the user's authorization and repository instructions.

A generated Skill must never say it searched, read, wrote, patched, ran shell, or executed Python unless the current host actually produced evidence of that action.

See `references/host-workspace-capabilities.md`.

## Host-native Python rule

`sandbox-python-executor` is an execution policy around host capabilities supplied by ChatGPT/Codex. It is not an MCP server and does not grant a Python tool.

When Python is available and materially improves correctness:

- execute deterministic work instead of mental simulation
- prefer bundled reviewed scripts when they already implement the check
- keep target-repository access read-only by default
- inspect untrusted target scripts before running them
- do not assume sandbox internet access
- return execution evidence

When unavailable, do not claim tests, validation, packaging, hashes, or generated files were executed.

See `references/host-python-sandbox.md`.

## Package preflight

Check at minimum:

- `.codex-plugin/plugin.json` is present and alone in its manifest directory
- declared component paths are safe and point to documented root locations
- required logo and composer icon are valid square images
- public Autopilot-produced Plugins contain committed light/dark SVG variants
- every direct child under `skills/` is a valid Skill directory
- `host-workspace-operator` is present when the Plugin's conversion plan requires local workspace operations
- Skill frontmatter is valid YAML (mapping with non-empty string `name` and `description`), body/identity are valid, and names are unique
- optional `agents/openai.yaml` is valid
- declared app/MCP files are structurally valid; undeclared `.app.json` / `.mcp.json` do not alter architecture and fail Skills-only public preflight
- package contains no secrets, bytecode, symlinks, excluded capabilities, normalization collisions, or local absolute user paths
- deterministic packager produces the same bytes from the same source

## Submission readiness

Use `references/submission-checklist.md` plus current official documentation. Verify publisher identity, listing fields, brand assets, public Skill inventory, host-capability claims, starter prompts, required reviewer cases, and MCP review material when applicable.

Never collapse `locally validated`, `submitted`, `approved`, and `published` into one status.

## Public-distribution safety gate

Review every public Skill name, description, instruction, reference, generated copy, capability label, and packaged executable behavior. Never blindly mirror all internal agents into a public Plugin.

When a capability must stay internal, remove every public replica, registration, generated Skill, runtime mirror, reference, index entry, and archive entry. Regeneration must not restore it.

Pass excluded slugs to the validator:

```bash
python3 <autopilot-skill>/scripts/validate_plugin.py <plugin-root> --exclude <slug> --json
```

## Strict generic preflight

When execution is available, actually run:

```bash
python3 <autopilot-skill>/scripts/validate_plugin.py <plugin-root> --json
python3 <autopilot-skill>/scripts/build_directory_pack.py <plugin-root> --json
python3 <autopilot-skill>/scripts/package_plugin.py <plugin-root> /tmp/plugin-a.zip --json
python3 <autopilot-skill>/scripts/package_plugin.py <plugin-root> /tmp/plugin-b.zip --json
cmp /tmp/plugin-a.zip /tmp/plugin-b.zip
unzip -Z1 /tmp/plugin-a.zip
```

Then extract to a clean directory and rerun `validate_plugin.py` against the extraction.

Repository-native quality, security, domain acceptance, and smoke checks remain additional gates.

## Learned failure patterns that must stay covered

- a loose `skills/registry.json` can be ignored by Skill import; move intended metadata under a valid owner and migrate consumers
- missing `interface.logo` or `interface.composerIcon` blocks directory branding validation
- a path such as `./assets/../assets/icon.svg` is unsafe even if it resolves inside the package
- extra files inside `.codex-plugin/` are misplaced
- undeclared `.app.json` / `.mcp.json` do not activate app/MCP capability and cannot remain in a Skills-only ZIP
- Skills-only packages cannot include `interface.screenshots`; MCP screenshots need one PNG/JPEG per starter prompt at 706x400–860
- Skill metadata `name` and directory slug are separate contracts
- `agents/openai.yaml` must be validated when bundled
- host-native read/write/search/grep/shell/patch/Python capabilities must not be represented as invented manifest dependencies
- a local install is evidence, not public directory approval
- GitHub/package authorship is not proof of verified OpenAI developer identity
- a good-looking logo or complete listing is not proof of technical validity
- a Plugin Skill can require execution behavior but cannot fabricate host tool availability

## Stop conditions

Stop before irreversible publication when required OpenAI rules cannot be verified, repository identity is ambiguous, credentials are unavailable, tests/validation fail, a target immutable version already exists, package identity is nondeterministic when determinism is promised, public copy contradicts behavior, publisher/legal listing facts are missing, reviewer evidence cannot be produced honestly, or the requested action exceeds authorization.

Do not weaken tests, hide uploader failures, rewrite released tags, inject registry credentials into CI, force-push unrelated history, overwrite customized workspace Skills without review, claim tool execution that did not occur, or claim Plugin Directory publication when only a local artifact was prepared.

Referenced files: 16

View saved version →

---
name: host-workspace-operator
description: Use when a ChatGPT/Codex Plugin workflow needs to inspect, search, modify, or verify files in the host workspace using the safest native tools available.
---

# Host Workspace Operator

Use workspace tools supplied by the current ChatGPT/Codex host instead of pretending the Plugin owns a filesystem API.

Tool names differ by surface. Route by capability, not by a hard-coded tool name. Typical capabilities include read, list, search, grep, write, patch, shell, and python.

## Capability order

Prefer the narrowest operation that can answer the task:

1. **read**: open a known file or exact range when the path is known.
2. **list**: enumerate a directory or workspace scope when filenames are unknown.
3. **search**: use semantic/content search when the user asks a broad question or exact wording is uncertain.
4. **grep**: use exact text or regex search when the term, symbol, field, or pattern is known.
5. **patch**: make a focused edit to an existing file when a patch-capable host tool exists.
6. **write**: create or replace a file only when the requested workflow requires a mutation.
7. **shell**: run repository commands when file tools are insufficient and command execution is appropriate.
8. **python**: use host-native Python for deterministic parsing, transformations, hashing, package inspection, or verification.

Do not use shell or Python just to imitate a safer read/search/file operation that the host already provides.

## Read-only first

Treat read, list, search, and grep as the default discovery phase. Inspect enough evidence to understand the current state before mutation.

For repository work:

- inspect repository instructions before editing
- prefer exact file/range reads after a search locates the relevant section
- avoid loading huge dependency/build trees without need
- honor ignored/generated/vendor directories when searching
- distinguish repository source from generated artifacts

## Mutation boundary

Write, patch, delete, move, rename, format, or command-based modification are **mutation** operations.

Before mutation:

- confirm the user requested or clearly authorized the change
- respect repository instructions and existing scope
- preserve unrelated work
- prefer a focused patch over full-file replacement
- avoid destructive shell commands when a file operation can do the job
- never write secrets into source, manifests, logs, examples, or release artifacts

After mutation:

- read the changed area back when practical
- run the relevant verifier/test when available
- report the exact files changed and verification evidence

## Search and grep rules

Use **search** for concepts and **grep** for exact patterns.

Examples:

- “Where is release approval implemented?” -> search first, then read likely files.
- “Find every `mcpServers` reference.” -> grep/exact search.
- “Which file contains the Plugin subtitle?” -> grep `shortDescription`/`subtitle`, then read the file.

Do not claim the entire workspace was searched if the host search covered only an index, limited scope, or returned a truncated result.

## Shell rules

Use shell when the workflow needs a command such as tests, git inspection, archive tooling, or repository-native validation.

- inspect commands before running them
- prefer read-only commands first
- avoid network-dependent commands unless network access is known and required
- do not execute arbitrary target-repository scripts merely because they exist
- never weaken tests or security checks just to obtain a passing result

## Python handoff

For deterministic computation or file processing, invoke `sandbox-python-executor` when it is packaged and the host exposes Python. Keep the same evidence rule: execution must actually happen before claiming a result.

## If a tool is unavailable

If a required host **tool is unavailable**:

- do not invent a replacement tool name or undocumented Plugin manifest field
- do not claim read/write/search/grep/shell/Python activity occurred
- use another available capability only when it preserves the task semantics and safety boundary
- otherwise state which operation is unavailable and keep the dependent result unverified

## Generated Plugin rule

Plugin Autopilot should install this Skill into newly converted Plugins when their workflows interact with files, repositories, generated artifacts, or local workspace state. It may also be included as a standard baseline Skill when the Plugin is intended for Codex-style repository work.

The Skill does not grant filesystem permissions. It teaches the model how to use host-native capabilities when present.

Referenced files: 1

View saved version →

---
name: plugin-brand-identity-designer
description: Use when a ChatGPT/Codex Plugin needs a production-ready visual identity and SVG logo system that clearly expresses the Plugin's job across light and dark surfaces.
---

# Plugin Brand Identity Designer

Create a small, distinctive identity for the Plugin after its public product boundary is clear. The logo must communicate the Plugin's actual job, not generic "AI" imagery.

## Required outputs

For every public Plugin prepared by Autopilot, create at minimum:

- `assets/logo-light.svg`
- `assets/logo-dark.svg`
- one square composer/icon asset suitable for small UI contexts
- a short brand rationale describing concept, geometry, palette, and small-size behavior

Prefer SVG for the logo system unless the current OpenAI contract or target surface requires another format. Keep all declared manifest assets package-relative and under `assets/`.

## Design procedure

1. Read the conversion brief and Plugin experience brief before drawing anything.
2. Reduce the product to one visual idea: what is being organized, checked, connected, created, translated, compared, or completed?
3. Sketch a symbol from that action or object relationship. Avoid symbols that could describe almost any AI product.
4. Build the mark with clean geometry and a square viewBox. It must remain recognizable at small sizes and in monochrome.
5. Produce light and dark variants from the same geometry. Do not make two unrelated logos.
6. Check contrast on both backgrounds. Do not rely on subtle low-contrast strokes to carry meaning.
7. Keep the SVG self-contained. Avoid external fonts, linked images, remote resources, scripts, filters that add fragility, or animation unless explicitly required and supported.
8. Use text in the logo only when the wordmark is essential and can be represented safely without depending on an unavailable font. A symbol-first mark is usually more portable for Plugin surfaces.
9. Create a simplified composer/icon asset when the full mark loses clarity at small size.
10. Validate every declared logo/icon path with the Autopilot validator before packaging.

## Creative quality gate

Reject or redraw a concept when it uses generic AI shorthand without a product-specific reason, including:

- robot heads
- brains or neural-network dots
- sparkle-only marks
- chat bubbles with no connection to the Plugin's actual job
- arbitrary circuit traces
- decorative gradients that carry no meaning
- tiny detail that disappears in a 32px icon
- a stock-looking monogram that could belong to an unrelated SaaS product

A good Plugin logo should be explainable in one sentence: "This shape represents X because the Plugin helps users do Y."

## SVG technical gate

Require:

- a square numeric `viewBox`
- valid XML/SVG markup
- no embedded secrets or remote URLs
- no absolute local file references
- deterministic source committed with the Plugin
- light and dark variants sharing the same core geometry

## Handoff

Pass the exact asset paths and brand rationale to `plugin-directory-listing-writer` and `submission-pack-builder`. Do not claim a dark-mode manifest field exists unless the current OpenAI documentation explicitly supports one; the dark SVG remains part of the packaged brand kit even when only one logo path is declared in the manifest.

View saved version →

---
name: plugin-directory-listing-writer
description: Use when a validated ChatGPT/Codex Plugin needs accurate Plugin Directory fields, discovery metadata, starter prompts, and reviewer-facing listing details grounded in the packaged product.
---

# Plugin Directory Listing Writer

Turn the exact Plugin artifact into clear public listing metadata. Treat listing copy as product metadata that affects both user understanding and model discovery.

## Authority and freshness

Re-check the current official OpenAI Plugin submission, packaging, metadata, and guideline pages before finalizing a public listing. Portal fields and limits can change. Current official documentation overrides remembered limits and examples.

## Required listing pack

Prepare these fields when the current portal requires them:

- Name
- Subtitle / short description
- Description / long description
- Category
- Developer name / verified developer identity
- Website URL
- Customer support URL
- Privacy policy URL
- Terms of Service URL
- Version
- Package name
- Capabilities
- logo asset
- starter prompts
- availability notes when relevant
- release notes

Use `build_directory_pack.py` to extract package-backed fields and expose missing portal-only material. Do not silently invent missing publisher or legal information.

## Writing rules

### Name

Use the customer-facing product or workflow name. Do not expose internal repository slugs unless they are already the public brand.

### Subtitle

Describe the plain user function in one short line. Prefer a direct verb or outcome. Keep it within the current portal limit; when the form specifies 30 characters, enforce 30 characters rather than relying on a looser package limit.

Avoid claims such as "best", "perfect", "revolutionary", or unverifiable performance language.

### Description

Explain:

1. what users can do with the Plugin
2. which repeatable workflows it covers
3. what external data/actions it needs, if any
4. material boundaries users should understand

Write from observable packaged behavior. Do not convert implementation detail into customer value claims.

### Developer identity

The developer name must match the verified individual or business identity selected in the OpenAI Platform submission flow. Never infer a legal publisher name from a GitHub username, repository owner, email domain, or package author field.

### URLs

Require public, accurate URLs. The support, privacy, terms, and website pages must match the actual publisher and data handling. Missing URLs are blockers for submission readiness when the current portal requires them.

### Capabilities

Use short user-facing capability statements. Each capability should describe meaningful work the Plugin can actually perform. Remove duplicates and internal mechanics.

### Starter prompts

Create prompts for the highest-value workflows, not cosmetic variants of the same request. Include direct and indirect phrasing where helpful. Test them against the final Plugin.

## Discovery evaluation

Build a golden prompt set before final metadata sign-off:

- direct prompts that explicitly name the Plugin or workflow
- indirect prompts that describe the desired outcome
- negative prompts where the Plugin should not trigger

Record expected behavior for each prompt. Revise names/descriptions when recall or precision is poor rather than stuffing unrelated keywords into metadata.

## Submission test material

When current OpenAI submission requirements call for reviewer test cases, prepare at least the required positive and negative cases. As of the 2026-08-22 baseline used by this repository, the official portal asks for at least five positive and three negative cases. Re-check before every submission.

Each positive case should state:

- user prompt
- expected Skill/tool/workflow behavior
- expected result shape
- fixture or account data required

Each negative case should state:

- prompt/scenario
- expected refusal, clarification, or fallback
- why the Plugin should not complete the action

## Output

Produce a directory pack with:

- source commit/ref and version
- exact field values
- character-count checks where applicable
- asset paths
- starter prompts
- golden prompt evaluation set
- reviewer tests
- missing publisher/legal information
- claims that still need evidence
- status: `listing_ready` or `not_ready`

Hand the pack to `submission-pack-builder`. Listing readiness is not submission, approval, or publication.

View saved version →

---
name: plugin-experience-architect
description: Use when a set of candidate Skills or app capabilities is technically valid but still needs to become a clear, useful ChatGPT/Codex Plugin that people can understand, discover, and invoke for real work.
---

# Plugin Experience Architect

Design the Plugin around user jobs rather than the source repository's internal taxonomy.

## Product decisions

1. State the primary user and the recurring job the Plugin should help complete.
2. Group candidate Skills by distinct user outcome. Merge duplicates and remove implementation-only capabilities from public discovery.
3. Make Skill boundaries mutually understandable: each Skill should answer a different invocation question.
4. Decide which external apps are required, optional, or unnecessary. A Skill should not force authentication unless its workflow truly depends on external data or actions.
5. Define the host-workspace capability profile. Decide whether the Plugin benefits from read, list, search, grep, write, patch, shell, and Python, and distinguish read-only discovery from mutation-capable operations.
6. For Plugins that interact with files, repositories, generated artifacts, or local workspace state, include `host-workspace-operator` as a baseline Skill. For deterministic computation/file processing, pair it with `sandbox-python-executor` when appropriate.
7. Write Plugin listing language from observable capability. Do not promise outcomes the packaged Skills/apps or current host cannot provide.
8. Choose capabilities that describe meaningful user work, not internal mechanics. Host-native operations may support a capability without becoming the marketing headline.
9. Write starter prompts as concrete tasks a user would genuinely ask. Cover the Plugin's highest-value workflows without repeating the same request in different words.
10. Review implicit invocation policy per Skill. Narrow, low-risk workflows may be suitable for implicit discovery; sensitive or destructive workflows need tighter invocation boundaries.
11. Check the portfolio for discovery collisions, jargon, unexplained acronyms, and source-project naming that means nothing to a new user.
12. Keep the public surface intentionally smaller than the repository when that produces a clearer product.
13. Define the one product idea the brand mark should express. Describe the relationship/action visually without prescribing generic AI symbols.
14. Create a discovery test brief with direct, indirect, and negative prompt families before final listing copy is frozen.

## Host-workspace capability profile

Record each operation with one of these dispositions:

- `preferred`: the Plugin commonly needs the operation when the host provides it
- `optional`: useful for some workflows but not required for the core job
- `mutation`: changes workspace state and needs an explicit authorization boundary
- `not_needed`: should not be surfaced merely because a host may provide it

Assess at least:

```text
read
list
search
grep
write
patch
shell
python
```

Do not describe these as permissions granted by the Plugin. They are host-native capabilities the Skill can use when present.

If the Plugin performs repository work, default read/list/search/grep to the discovery phase. Treat write/patch and mutating shell commands as mutation operations. Use Python for deterministic local computation and verification, not as a generic substitute for narrower file/search tools.

## Decision test

For every public Skill, answer:

- Who needs this?
- What triggers it?
- What finished result does it produce?
- Why is this a separate Skill rather than part of another one?
- Does it require an app or runtime dependency?
- Which host-native read/search/mutation capabilities help complete it?
- What could go wrong if it is invoked implicitly?
- What source evidence proves the workflow is real?

If these answers are weak, return the candidate to discovery/compilation instead of polishing the listing.

## Output

Produce a Plugin experience brief containing:

- primary audience and recurring job
- public Skill set and exclusions
- required/optional app dependencies
- host-workspace capability profile
- mutation boundary for write/patch/shell actions
- whether `host-workspace-operator` should be installed
- whether `sandbox-python-executor` is needed
- Plugin promise grounded in packaged behavior
- capability list
- up to three starter prompt directions
- direct, indirect, and negative discovery-prompt directions
- invocation-policy notes
- one visual idea for the brand mark
- listing risks or unsupported claims

## Handoff order

Do not jump straight from product design to submission.

1. If the target Plugin uses local files or repository state, install the canonical workspace Skill with `install_host_workspace_skill.py`. Do not overwrite an existing customized version without review.
2. Hand the stable Plugin concept to `plugin-brand-identity-designer` for the light/dark SVG identity pack and compact composer/icon asset.
3. Hand the exact capabilities, starter prompts, brand paths, host-workspace profile, and discovery test brief to `plugin-directory-listing-writer`.
4. Run the main Autopilot package validator and `build_directory_pack.py` against the exact artifact.
5. Only after those gates pass, hand the artifact and evidence to `submission-pack-builder`.

If workspace capability planning, branding, or listing work exposes a confused product boundary, return to this Skill instead of polishing around the problem.

View saved version →

---
name: sandbox-python-executor
description: Use when a ChatGPT/Codex Plugin workflow needs deterministic computation, file processing, repository checks, package inspection, or other work that should be actually executed with host-native Python instead of answered from unverified reasoning.
---

# Sandbox Python Executor

Use the host's own Python execution capability to produce evidence, not just code suggestions.

OpenAI calls Code Interpreter the **python tool**. In ChatGPT, when that tool is available for the current conversation, use it for the execution steps in this Skill. In Codex, use the host execution environment available to the session and run Python there when Python is the appropriate runtime.

This Skill does not create a new remote runtime and does not declare an MCP dependency. Tool availability belongs to the host. The workflow below governs what to do when host-native Python is available and what to report when it is not.

## When to execute Python

Use host-native Python when the requested workflow materially benefits from real execution, including:

- parsing or comparing JSON, YAML-like text, manifests, or generated reports
- inspecting archives and package contents
- computing SHA256 or other deterministic hashes
- checking file trees, paths, duplicate names, or package boundaries
- running the dependency-free Python scripts bundled with Plugin Autopilot
- validating generated files or structured output
- transforming user-provided files when Python is the appropriate local tool
- reproducing a bug or verifying a deterministic calculation

Do not invoke Python merely to rewrite prose, brainstorm names, or perform a trivial fact lookup where execution adds no evidence.

## Execution rule

When the **python tool** is available and the task requires executable verification:

1. Actually execute the relevant Python. Do not merely print commands or provide a code block as a substitute for execution.
2. Prefer Plugin Autopilot's bundled, reviewed scripts over ad-hoc reimplementations when they already cover the required check.
3. Keep target-repository access read-only unless the user has requested a mutation and the surrounding workflow permits it.
4. Treat scripts from an arbitrary target repository as untrusted input. Inspect them before execution; do not automatically run repository-native scripts just because they exist.
5. Do not assume network access from the sandbox. Use web/search tools separately when current external information is required.
6. Do not expose secrets, environment credentials, tokens, or unrelated user files in logs or outputs.
7. Iterate on Python failures when the failure is caused by your own code or invocation and a safe correction is available.
8. Preserve generated files the user needs and return their host-provided file reference/path when the surface supports it.

## Plugin Autopilot execution sequence

For a local Plugin artifact mounted in the host sandbox, use Python to run the applicable evidence-producing stages rather than only describing them:

```text
analyze_repo.py
        -> candidate/architecture evidence
build_directory_pack.py
        -> listing evidence
validate_plugin.py
        -> package preflight evidence
package_plugin.py x2
        -> deterministic archive evidence
fresh extraction + validate_plugin.py
        -> installable-artifact evidence
```

Run only the stages relevant to the user's request. Repository-native tests remain separate evidence and should be run through the safest host execution facility available when the workflow requires them.

## Execution evidence

After execution, report enough evidence to distinguish a real run from a proposed command. Include the relevant subset of:

- tool/runtime actually used
- script or operation executed
- exit/pass/fail status
- important counts or validation findings
- generated file path or artifact reference
- SHA256 when package identity matters
- warnings or skipped checks

Never fabricate stdout, hashes, paths, test counts, or generated artifacts.

## If the tool is unavailable

If the **python tool is unavailable** in the current host/session:

- **Do not claim** that Python, tests, validators, packaging, or file processing were executed.
- State that the host-native Python execution capability is unavailable for this run.
- Continue with static inspection or reasoning only when that can answer the request honestly.
- Mark execution-dependent conclusions as unverified.
- If another safe host execution facility is available in Codex, it may be used instead and must be identified accurately.

Do not invent a Plugin manifest field, `agents/openai.yaml` dependency, MCP server, or remote code runner solely to pretend that ChatGPT's Python sandbox is available.

## Boundary

This Skill is an execution policy for host-native tooling. It is not a general arbitrary-code-execution service for other users or remote systems. Keep Plugin Autopilot skills-only unless a separate product requirement genuinely needs an external authenticated action/data boundary.

Referenced files: 1

View saved version →

---
name: submission-pack-builder
description: Use when an exact ChatGPT/Codex Plugin artifact has passed local package, brand, and listing gates and you need reviewer-ready submission evidence without confusing preparation, submission, approval, and publication states.
---

# Submission Pack Builder

Prepare evidence for the exact validated artifact. Do not use submission copy to hide unresolved package, brand, listing, or product problems.

## Preconditions

Require:

- exact Plugin version/ref
- successful repository-native tests
- successful Autopilot package preflight
- deterministic package result when promised
- reviewed public Skill set and exclusions
- architecture decision: `skills-only`, `MCP-backed`, or `hybrid`
- reviewed Plugin experience brief
- product-specific SVG brand pack with light and dark variants plus the declared small icon/composer asset
- successful directory listing pack with no blocking missing fields
- verified developer/business identity still confirmed in the OpenAI submission surface rather than inferred from repository metadata

If the host also provides a dedicated Skill Submission Pack Writer, use it for current portal-facing prose and field formatting after these evidence requirements are satisfied. This Skill remains the evidence contract and status gate.

## Build the pack

1. Re-check the current official OpenAI submission requirements.
2. Record the artifact SHA256 and source commit/ref.
3. Summarize the Plugin's user-facing job in plain language tied to actual packaged capabilities.
4. List each public Skill and any required/optional app dependency.
5. Record public exclusions from the source repository and why they were excluded.
6. Include the exact directory listing fields and brand asset paths used for the artifact. Do not substitute a draft listing from another ref or version.
7. Include discovery evidence from direct, indirect, and negative golden prompts when available. Record routing misses or ambiguous metadata instead of hiding them.
8. Build reviewer test cases from real Plugin behavior. Positive cases should cover intended workflows; negative cases should show boundaries, refusal, clarification, fallback, or non-trigger behavior where relevant.
9. At the repository's 2026-08-22 OpenAI baseline, require at least five positive and three negative reviewer cases. Re-check the live official requirement before every public submission.
10. For MCP-backed/hybrid Plugins, document server/auth model, read/write behavior, sensitive actions, reviewer access requirements, tool annotations, and current production evidence required by the official submission flow.
11. Verify listing fields, branding, URLs, privacy/terms/support claims, category, package name, version, and capabilities against the exact artifact.
12. Record unresolved warnings instead of converting them into confident public claims.
13. Emit one status only: `submission_ready` or `not_ready`, with blockers.

## Status discipline

Never use these as synonyms:

- `brand_ready`
- `listing_ready`
- `locally_validated`
- `submission_ready`
- `submitted`
- `approved`
- `published`

A reviewer packet proves preparation, not acceptance by OpenAI.

## Evidence output

The pack should contain or reference:

- source ref and artifact hash
- architecture
- public Skill/app inventory
- public exclusions
- brand rationale and exact light/dark/icon asset paths
- exact listing fields and field-limit checks
- developer identity verification status
- golden prompt set and discovery observations
- reviewer test cases
- privacy/terms/support URLs where applicable
- MCP review material where applicable
- validation and deterministic-package evidence
- residual warnings
- exact submission state

Use `../chatgpt-codex-plugin-autopilot/references/submission-checklist.md`, `../chatgpt-codex-plugin-autopilot/references/branding-and-listing.md`, and current official OpenAI documentation as the authority chain.

View saved version →

---
name: workflow-to-skill-compiler
description: Use when a repository has a valuable agentic workflow, prompt chain, playbook, command, or runbook that should become a portable ChatGPT/Codex Skill without losing its real decision logic.
---

# Workflow to Skill Compiler

Convert source workflows into portable Skills. Preserve behavior, not file shape.

## Compilation rules

1. Define one user job for the Skill. If the source mixes unrelated jobs, split it before conversion.
2. Trace the source workflow from trigger to evidence, decisions, actions, validation, and stop conditions.
3. Write Skill metadata for discovery. The `description` must say when to use the Skill, not merely what topic it contains.
4. Keep the main `SKILL.md` focused on execution. Move deep reference material into `references/` and deterministic mechanical helpers into `scripts/`.
5. Replace source-repository assumptions with portable contracts. Remove absolute paths, personal machine locations, private aliases, hidden environment assumptions, and undocumented dependencies.
6. Preserve meaningful gates. Do not flatten approval, safety, testing, evidence, or verification steps just to make the Skill shorter.
7. Prefer host capabilities over unnecessary bundled runtime code. Add MCP only when the workflow genuinely needs external data/actions that cannot be represented honestly as Skill guidance.
8. Keep tool names capability-oriented where possible so the Skill can travel across compatible hosts.
9. When the workflow touches files, repositories, generated artifacts, or local workspace state, integrate the `host-workspace-operator` contract. Prefer read/list/search/grep for discovery, patch/write only for authorized mutations, shell for repository commands, and `sandbox-python-executor` for deterministic Python work.
10. Add `agents/openai.yaml` only when interface metadata, product targeting, invocation policy, icons, or documented MCP tool dependencies materially improve the Skill. Do not invent dependencies for host-native filesystem, shell, patch, search, or Python tools.
11. Run public-distribution review before packaging. Internal workflows may contain capabilities that should never be mirrored into a public Skill.

## Workspace-capability compilation

When the source workflow includes operations such as:

- reading files
- listing directories
- searching concepts or filenames
- exact grep/regex lookup
- creating or editing files
- applying focused patches
- running tests or repository commands
- deterministic Python/file processing

represent those operations as host-native capability requirements in the Skill instructions. Do not hard-code one product's tool names unless the current host contract requires it.

For generated Plugins, the main Autopilot should install the canonical workspace Skill with:

```bash
python3 <autopilot-skill>/scripts/install_host_workspace_skill.py <target-plugin>
```

The installer is intentionally non-destructive. If the target already contains a customized `host-workspace-operator`, review it instead of overwriting it.

## Quality gate

Reject the compilation if:

- it is mostly a pasted prompt with no operating logic
- it cannot explain its trigger and completion condition
- it depends on files that will not exist after installation
- it silently drops source validation or approval gates
- multiple Skills are near-duplicates with different names
- the Skill description is so broad that it will collide with unrelated workflows
- generated instructions claim tools or permissions the Plugin does not actually provide
- mutation operations are mixed into read-only discovery without a clear authorization boundary
- the Skill says it searched, read, wrote, patched, ran shell, or executed Python without host evidence

## Handoff

After compilation, pass the Skill set and its workspace-capability needs to `plugin-experience-architect`. The experience brief should state which host-native operations the Plugin benefits from and which are mutation-capable. Then run the main Autopilot generation and validation gates.