Plugin Experience Architect
Design the Plugin around user jobs rather than the source repository's internal taxonomy.
Product decisions
- State the primary user and the recurring job the Plugin should help complete.
- Group candidate Skills by distinct user outcome. Merge duplicates and remove implementation-only capabilities from public discovery.
- Make Skill boundaries mutually understandable: each Skill should answer a different invocation question.
- 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.
- 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.
- 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.
- Write Plugin listing language from observable capability. Do not promise outcomes the packaged Skills/apps or current host cannot provide.
- Choose capabilities that describe meaningful user work, not internal mechanics. Host-native operations may support a capability without becoming the marketing headline.
- 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.
- Review implicit invocation policy per Skill. Narrow, low-risk workflows may be suitable for implicit discovery; sensitive or destructive workflows need tighter invocation boundaries.
- Check the portfolio for discovery collisions, jargon, unexplained acronyms, and source-project naming that means nothing to a new user.
- Keep the public surface intentionally smaller than the repository when that produces a clearer product.
- Define the one product idea the brand mark should express. Describe the relationship/action visually without prescribing generic AI symbols.
- 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:
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.
- 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.
- Hand the stable Plugin concept to
plugin-brand-identity-designer for the light/dark SVG identity pack and compact composer/icon asset.
- Hand the exact capabilities, starter prompts, brand paths, host-workspace profile, and discovery test brief to
plugin-directory-listing-writer.
- Run the main Autopilot package validator and
build_directory_pack.py against the exact artifact.
- 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.
1---2name: plugin-experience-architect3description: 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.4---56# Plugin Experience Architect78Design the Plugin around user jobs rather than the source repository's internal taxonomy.910## Product decisions11121. State the primary user and the recurring job the Plugin should help complete.132. Group candidate Skills by distinct user outcome. Merge duplicates and remove implementation-only capabilities from public discovery.143. Make Skill boundaries mutually understandable: each Skill should answer a different invocation question.154. 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.165. 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.176. 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.187. Write Plugin listing language from observable capability. Do not promise outcomes the packaged Skills/apps or current host cannot provide.198. Choose capabilities that describe meaningful user work, not internal mechanics. Host-native operations may support a capability without becoming the marketing headline.209. 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.2110. Review implicit invocation policy per Skill. Narrow, low-risk workflows may be suitable for implicit discovery; sensitive or destructive workflows need tighter invocation boundaries.2211. Check the portfolio for discovery collisions, jargon, unexplained acronyms, and source-project naming that means nothing to a new user.2312. Keep the public surface intentionally smaller than the repository when that produces a clearer product.2413. Define the one product idea the brand mark should express. Describe the relationship/action visually without prescribing generic AI symbols.2514. Create a discovery test brief with direct, indirect, and negative prompt families before final listing copy is frozen.2627## Host-workspace capability profile2829Record each operation with one of these dispositions:3031- `preferred`: the Plugin commonly needs the operation when the host provides it32- `optional`: useful for some workflows but not required for the core job33- `mutation`: changes workspace state and needs an explicit authorization boundary34- `not_needed`: should not be surfaced merely because a host may provide it3536Assess at least:3738```text39read40list41search42grep43write44patch45shell46python47```4849Do not describe these as permissions granted by the Plugin. They are host-native capabilities the Skill can use when present.5051If 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.5253## Decision test5455For every public Skill, answer:5657- Who needs this?58- What triggers it?59- What finished result does it produce?60- Why is this a separate Skill rather than part of another one?61- Does it require an app or runtime dependency?62- Which host-native read/search/mutation capabilities help complete it?63- What could go wrong if it is invoked implicitly?64- What source evidence proves the workflow is real?6566If these answers are weak, return the candidate to discovery/compilation instead of polishing the listing.6768## Output6970Produce a Plugin experience brief containing:7172- primary audience and recurring job73- public Skill set and exclusions74- required/optional app dependencies75- host-workspace capability profile76- mutation boundary for write/patch/shell actions77- whether `host-workspace-operator` should be installed78- whether `sandbox-python-executor` is needed79- Plugin promise grounded in packaged behavior80- capability list81- up to three starter prompt directions82- direct, indirect, and negative discovery-prompt directions83- invocation-policy notes84- one visual idea for the brand mark85- listing risks or unsupported claims8687## Handoff order8889Do not jump straight from product design to submission.90911. 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.922. Hand the stable Plugin concept to `plugin-brand-identity-designer` for the light/dark SVG identity pack and compact composer/icon asset.933. Hand the exact capabilities, starter prompts, brand paths, host-workspace profile, and discovery test brief to `plugin-directory-listing-writer`.944. Run the main Autopilot package validator and `build_directory_pack.py` against the exact artifact.955. Only after those gates pass, hand the artifact and evidence to `submission-pack-builder`.9697If workspace capability planning, branding, or listing work exposes a confused product boundary, return to this Skill instead of polishing around the problem.