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:

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.