Plugin CLAUDE.md doesn't surface deploy/secrets skills as authoritative for gapp_* tool use

[krisrowe]

Problem

The plugin's CLAUDE.md is a one-line pointer to README.md and
CONTRIBUTING.md. It carries no signal to agents about when (or
how) to use the gapp_* MCP tools the plugin ships, and no
pointer to the deploy or secrets skills as the authoritative
operational guide.

The skills themselves do declare invocation triggers in their
SKILL.md frontmatter — phrases like "deploy this to cloud run",
"help me get this hosted", "set up CI/CD", etc. Those fire when
a user types something matching the trigger. But agents also
reach for gapp_* MCP tools autonomously — e.g., when an
operator asks to "deploy this app to cloud" and the agent
notices the gapp MCP server is registered. In that path the
trigger phrases don't fire reliably, and the agent ends up
reasoning about gapp's behavior from the MCP tool schemas
alone.

That's how I just spent a non-trivial chunk of a downstream
session confabulating storage decisions (GCS FUSE vs single-
instance pin vs remote backend) from generic Cloud Run knowledge,
when the deploy skill clearly states: gapp always uses FUSE,
storage is automatic, operators don't choose. The MCP tool
schemas for gapp_init / gapp_setup / gapp_deploy describe
parameters but not the operational model. The skill describes the
operational model. An agent that doesn't load the skill makes
wrong calls.

Why the plugin CLAUDE.md should carry this

Plugin context is the right home for "if you're using this
plugin's tools, here's the guidance every consumer should
follow," because:

1. Every user of the plugin gets it automatically. No
   need to write the rule into a personal CLAUDE.md /
   CONTEXT.md. Anyone who installs gapp inherits the same
   agent behavior.
2. It's specific to this plugin's lifecycle. Not a
   cross-cutting concern that belongs in a user's global
   context.
3. It complements the SKILL.md frontmatter triggers. Those
   trigger phrases catch user-typed intent. The plugin CLAUDE.md
   catches agent-decided tool selection.

Proposed change

Update CLAUDE.md at the plugin root to do three things:

1. Point at the skills as authoritative. Something like:

   Before invoking any gapp_* MCP tool autonomously, load
   the deploy skill (and secrets skill if managing
   secrets). The tool schemas describe the API surface; the
   skills describe the operational model. Do not extrapolate
   deploy decisions (storage, build, secrets, auth, custom
   domain, CI) from tool schemas alone — those decisions are
   opinionated and the skills carry the opinions.

2. Keep the existing pointer to README / CONTRIBUTING. Those
   are still the right human-facing entrypoints for usage
   reference and architecture.

3. Don't duplicate skill content. The CLAUDE.md should be
   short — a few sentences that route the agent to the right
   skill, not a copy of the skill.

Non-goals

• Not changing what the deploy or secrets skills say. (Other
  issues — e.g., Document language-agnostic Dockerfile support #19 — own the skill description scope.)
• Not changing the MCP tool schemas. They're API documentation;
  they don't need to carry lifecycle guidance.
• Not adding a personal-context rule for every user of the
  plugin. That's what this issue is fixing.

Acceptance criteria

A fresh agent session in a repo that has the gapp plugin
installed but no prior gapp history, asked to "deploy this app
to cloud" or "host this on Cloud Run", should:

• Recognize gapp_* tools are available
• Load the deploy skill before calling any gapp_* tool that
  isn't a pure status query
• Make deploy decisions consistent with the skill (e.g., never
  propose manual storage wiring, FUSE-or-no-FUSE choices,
  single-instance pinning, etc. — gapp already decided)
• Refer to README / CONTRIBUTING only for usage commands and
  architecture context, not for lifecycle decisions (which live
  in the skills)

Work breakdown

• Update CLAUDE.md at the plugin root to surface
  deploy and secrets skills as authoritative for any
  autonomous gapp_* tool invocation. Keep it short.
• Verify the change is loaded by the plugin's distribution
  mechanism (i.e., CLAUDE.md is actually consumed as agent
  context when the plugin is installed; if not, this issue
  becomes about the plugin loader, not the content).
• Sanity-check with a fresh session: ask an agent to deploy
  something using the plugin and confirm it loads the skill
  before reasoning about storage / build / secrets.

Notes

• This issue is filed from a session where I (the agent) made
  the exact mistake this change is designed to prevent. The
  user had to interrupt and ask "why didn't you load the skill?"
  before I went looking for it. The user's reaction was the
  forcing function for this filing.
• A more general principle (agents should always check for
  plugin-shipped skills before using plugin-shipped tools)
  belongs in the agent platform itself, not in any one plugin.
  But until that platform-level fix exists, each plugin owning
  its own CLAUDE.md surface is the practical workaround.