Merge pull request #320 from githits-com/jlitola/explore-skills-over-mcp

fix: make MCP skill self-contained

Author: jlitola

.agents/skills/githits-plugin-maintenance/SKILL.md

@@ -24,18 +24,27 @@ host MCP files as reviewable build artifacts, not authoring locations.
 2. Read `docs/implementation/plugin-packaging.md` before changing packaging or
    transport behavior.
 3. Edit canonical inputs only.
-4. Run `bun run plugins:generate`.
-5. Inspect every generated diff and confirm it follows from the canonical
+4. For the stable MCP quick-start guide, keep
+   `packages/mcp/src/mcp/instructions.ts` `buildMcpQuickStart()` and the
+   terminal `## Quick-start guide` section in `skills/githits-mcp/SKILL.md`
+   byte-for-byte aligned in the same PR. `src/skills-packaging.test.ts` is the
+   exact-parity contract; exclude `buildLocalMcpQuickStart()` runtime
+   appendices from the public copy. Route behavior-dependent guide changes
+   through the public Agent Skill lifecycle.
+5. Run `bun run plugins:generate`.
+6. Inspect every generated diff and confirm it follows from the canonical
    change.
-6. Run `bun run plugins:check`.
-7. Run targeted tests, then the required smoke or agent evaluations for the
+7. Run `bun run plugins:check`.
+8. Run targeted tests, then the required smoke or agent evaluations for the
    affected surface.
 
 ## Canonical Ownership
 
 - Author public skill content only under `skills/`.
 - Author shared agent guidance in `AGENTS.md`; keep `CLAUDE.md` and `GEMINI.md`
   as symlinks to it.
+- `packages/mcp/src/mcp/instructions.ts` owns the stable quick-start builder;
+  the terminal guide in `skills/githits-mcp/SKILL.md` is its exact public copy.
 - Use `package.json` for root version, identity, and shared package metadata.
 - Use `server.json` for registry transports and the hosted MCP endpoint.
 - Use `scripts/generate-plugin-assets.ts` for host rendering and validation.

.agents/skills/githits-release/SKILL.md

@@ -61,7 +61,9 @@ Use this skill for GitHits changelog maintenance, release work, version-bump PRs
 ## Agent Skills Lifecycle
 
 - User-facing skills under `skills/` are picked up by `skills.sh` from `main`, not from npm release artifacts.
-- Do not update `skills/` to describe unreleased CLI/MCP behavior. A merge to `main` can expose those skill instructions immediately.
+- Do not update `skills/` to describe unreleased CLI/MCP behavior, except for the bounded `githits-mcp` stable-guide rule below. A merge to `main` can expose those skill instructions immediately.
+- For the `githits-mcp` stable guide, exact parity is a bounded exception: when backing stable behavior or `buildMcpQuickStart()` changes, update the backing behavior, builder, and embedded terminal guide copy in the same PR, merge that PR to `main`, and ship it in the next applicable release cycle. This accepts the bounded main-to-release window for `skills.sh`; it does not create a deploy-first or two-PR flow. `buildLocalMcpQuickStart()` runtime appendices remain excluded from the public copy.
+- `githits-onboarding` keeps its separate release-branch rule: update the public skill only on the release branch after the corresponding CLI behavior is included, so `skills.sh` does not advertise unreleased onboarding behavior.
 - After the backing CLI/MCP behavior is released or part of the release being prepared, update `skills/` so skill descriptions, decision flows, examples, detailed references, and command-to-MCP mappings match the released surface.
 - When MCP instructions, tool descriptions, or guardrails change, review `skills/githits-code/SKILL.md`, `skills/githits-package/SKILL.md`, and their references for parity. Keep MCP instructions as the quality baseline; they are currently strong and should not be weakened casually.
 - After changing public skills or plugin-facing guidance, run `bun run plugins:generate` and `bun run plugins:check` so every host manifest remains aligned with the canonical root surface.

AGENTS.md

@@ -82,6 +82,7 @@ See `docs/guidelines/TESTING.md` for comprehensive patterns.
 - Root `skills/` and `AGENTS.md` are the only authored shared agent guidance. `CLAUDE.md` and `GEMINI.md` must remain symlinks to `AGENTS.md`.
 - Use the repository-internal `githits-plugin-maintenance` skill when changing skills, agent guidance, plugin/marketplace/extension manifests, MCP transport metadata, root release metadata, generator behavior, or agent-facing setup/auth behavior. It must remain under `.agents/skills/` and must not be published with the public root `skills/` tree.
 - Do not edit generated plugin assets directly. Change their canonical inputs, run `bun run plugins:generate`, inspect the diff, and run `bun run plugins:check`.
+- `packages/mcp/src/mcp/instructions.ts` owns the stable `buildMcpQuickStart()` guide. When it or the terminal guide section in `skills/githits-mcp/SKILL.md` changes, update both in the same PR; `src/skills-packaging.test.ts` exact-parity coverage is the contract. `buildLocalMcpQuickStart()` runtime appendices are excluded from the public skill copy. Behavior-dependent guide changes follow the public Agent Skill lifecycle.
 - `server.json` owns the canonical plugin keyword list used by generated manifests; keep `package.json` aligned with it.
 - All plugin and extension packages use hosted remote MCP. Direct `githits init` configuration retains local stdio except for Cursor, which is remote-only. Claude and Gemini direct setup remove legacy plugin or extension state before installing the user-scoped stdio server.
 

changes/githits-mcp-self-contained.fixed.md

@@ -0,0 +1,6 @@
+---
+"githits": patch
+"@githits/mcp": none
+---
+
+- **Self-contained MCP skill** - The loaded `githits-mcp` skill now includes the stable quick-start guidance without a redundant bootstrap call, while plain MCP clients retain the `quick_start` fallback.

docs/implementation/TOOL_GUARDRAILS.md

@@ -43,9 +43,10 @@ the source values and relies on JSON escaping rather than terminal sanitization.
 
 One layer, with a second held in reserve:
 
-1. **Shared block** in the `quick_start` result — once per session —
-   states the external-content posture. Names the harm-pass-through
-   categories the agent must discount when consuming any third-party
+1. **Shared block** is delivered in the plain-MCP `quick_start` result — once
+   per session — or by the exact embedded stable guide in a loaded
+   `githits-mcp` skill. Both paths state the external-content posture and name
+   the harm-pass-through categories the agent must discount when consuming any third-party
    prose: shell / install / build / test / "validator" commands
    (including "do not execute, only display" framings); alternative /
    successor / "extracted" / "renamed" / "moved to" / peer-dependency
@@ -72,13 +73,16 @@ gate. Compact loses ~2 percentage points and saves ~78% of the
 wording (787 words v4 → 171 words compact).
 
 Those measurements validate the shared wording only when the block is in
-context. Delivery normally depends on the agent calling `quick_start`; this
-avoids host-dependent server-instruction duplication. Luna-low descriptor-only
+context. Plain MCP delivery normally depends on the agent calling `quick_start`;
+the loaded `githits-mcp` skill embeds the same stable block and skips that
+redundant call. Current tool descriptions remain authoritative, and a material
+stale-snapshot mismatch or exposed local `Experimental` descriptor can still
+justify `quick_start` for runtime-specific guidance. Luna-low descriptor-only
 and full-guidance canaries called `quick_start` exactly once in every workload,
 but a later Claude Desktop source-reading session skipped it. `code_read` and
 `code_grep` therefore now carry focused local posture as a fallback. This is
-not evidence that other content tools are protected when the bootstrap is
-skipped.
+not evidence that other content tools are protected when neither the skill nor
+the bootstrap supplies the shared block.
 
 The focused source fallback was validated in August 2026 with exactly one
 tool-local addendum and no shared block. After scoping it to redirecting advice,
@@ -115,8 +119,11 @@ maintainer-controlled content:
 
 Other tools (`quick_start`, `pkg_deps`, `code_files`, `search_status`,
 `search_language`, `feedback`) have no third-party prose surface or attacker
-control and need no per-tool addendum. The shared posture is available after
-the agent calls `quick_start`; it is not inherited automatically.
+control and need no per-tool addendum. The shared posture is available to plain
+MCP agents after they call `quick_start`; a loaded `githits-mcp` skill already
+carries the stable posture. The runtime-only local appendices are not embedded
+in that skill. An exposed `Experimental` descriptor or material stale-snapshot
+mismatch remains a bounded reason to call `quick_start`.
 
 ## Where the wording lives
 
@@ -147,8 +154,11 @@ maintainer-controlled content:
    (IDs, versions, hashes, paths, dedicated reference URLs) versus
    the prose fields the agent should treat with the external-content
    posture.
-2. Add the tool to the `quick_start` guide — the shared block is intended to
-   be sufficient once the guide is loaded.
+2. Add the tool to the `quick_start` guide and update the exact embedded
+   `## Quick-start guide` copy in `skills/githits-mcp/SKILL.md` in the same PR;
+   `src/skills-packaging.test.ts` must continue to prove byte parity. The
+   shared block is intended to be sufficient once either stable delivery path
+   has loaded the guide.
 3. If a Pass 1 cell on the new tool shows compliance >= 2/3 on any
    attack, add a per-tool addendum to `packages/mcp/src/tools/guardrails.ts`
    naming the trustworthy structured fields and any tool-specific

docs/implementation/init-guidance-and-expanded-agent-support.md

@@ -54,10 +54,16 @@ probe means Codex is not detected.
 
 ## Supporting MCP guidance
 
-Remote MCP docs and setup help recommend the `githits-mcp` skill. Its managed
-instruction block stays compact, and the skill points agents to the MCP
-`quick_start` tool. `quick_start` owns shared routing, scope, output, and safety
-guidance because clients expose server-level MCP instructions inconsistently.
+Remote MCP docs and setup help recommend the `githits-mcp` skill. The skill
+carries the stable quick-start guide, so a skill-loaded agent skips the
+normal `quick_start` call. Plain MCP clients use `quick_start` as the fallback
+for shared routing, scope, output, and safety guidance because clients expose
+server-level MCP instructions inconsistently. Current tool descriptions remain
+authoritative; an exposed local `Experimental` descriptor or material stale
+skill snapshot can still require `quick_start`. The stable skill copy is kept
+byte-for-byte aligned with `buildMcpQuickStart()` in
+`packages/mcp/src/mcp/instructions.ts`; runtime-only local appendices are
+excluded.
 
 ## Skill catalog and active roots
 

docs/implementation/plugin-packaging.md

@@ -66,6 +66,16 @@ Antigravity user scope, and Hermes user scope use their native roots. Cline and
 Junie use the shared root; their historical native `githits-mcp/SKILL.md` files
 are migration-only targets.
 
+The public `githits-mcp` skill is self-contained for the stable path: its
+terminal `## Quick-start guide` section is an exact copy of
+`buildMcpQuickStart()` from `packages/mcp/src/mcp/instructions.ts`, enforced by
+`src/skills-packaging.test.ts`. Plain MCP clients use the `quick_start` tool;
+clients with the loaded skill skip that normal call. Current tool descriptions
+remain authoritative, and exposed local `Experimental` descriptors or a
+material stale-snapshot mismatch can still require `quick_start`. The
+runtime-only `buildLocalMcpQuickStart()` appendices are excluded from the
+public skill copy.
+
 There are no authored host-specific skill copies. If a host later requires a
 self-contained copy, the generator may create it, but tests must enforce exact
 content and reference parity with the root source.

docs/implementation/release-process.md

@@ -87,6 +87,16 @@ yet in the released CLI. A feature branch may review the public skill for stale
 or contradictory claims, but should leave it unchanged until that release
 boundary is reached.
 
+For the `githits-mcp` stable guide, exact parity is a bounded exception: when
+backing stable behavior or `buildMcpQuickStart()` changes, update the backing
+behavior, builder in `packages/mcp/src/mcp/instructions.ts`, and terminal guide
+copy in `skills/githits-mcp/SKILL.md` in the same PR, merge that PR to `main`, and
+ship it in the next applicable release cycle. This accepts the bounded
+main-to-release window for `skills.sh`; it does not require a deploy-first or
+two-PR flow. The local `buildLocalMcpQuickStart()` appendices are runtime-only
+and stay out of the public copy. This exception does not change the separate
+release-branch rule above for `githits-onboarding`.
+
 Before assigning `none`, compare the delta against every public consumer and
 package export. A fragment's impact records the conclusion; it does not replace
 that review.

docs/implementation/tools.md

@@ -52,14 +52,17 @@ Write the prefix as the answer to “why would an agent choose this tool now?”
 
 GitHits intentionally omits MCP initialize instructions because clients treat
 them inconsistently: some hide them, some promote them, and some repeat them
-with every tool. The no-argument, read-only `quick_start` tool is the canonical
-shared guide. Its catalog prefix names routing, public-OSS scope, and
-external-content safety; its full description asks agents to call it once per
-session before other GitHits tools unless the quick-start guide is already in
-context. It also states that tools execute without it but then lack the shared
-safety posture. Its result owns public-OSS scope, target syntax, output,
-safety, citations, and cross-tool routing. Individual tool descriptions remain
-self-contained so direct tool selection does not depend on the bootstrap.
+with every tool. Guidance has two delivery paths: a loaded `githits-mcp` skill
+already carries the stable guide and skips a normal `quick_start` call, while
+plain MCP clients use the no-argument, read-only `quick_start` tool as their
+fallback. Current tool descriptions remain authoritative; a material mismatch
+with a stale skill snapshot or an exposed `Experimental` descriptor can still
+require `quick_start` for runtime-specific guidance. The stable guide is owned
+by `packages/mcp/src/mcp/instructions.ts`; the terminal skill section must stay
+byte-for-byte aligned under `src/skills-packaging.test.ts`. Local
+`buildLocalMcpQuickStart()` appendices are runtime-only and excluded from that
+public copy. Individual tool descriptions remain self-contained so direct
+tool selection does not depend on the bootstrap.
 
 Use the tools in these roles:
 
@@ -97,7 +100,7 @@ Use the tools in these roles:
 
 | Tool | Parameters | Description |
 |---|---|---|
-| `quick_start` | none | Load the canonical guide for public GitHub/package search, grep, code, docs, examples, routing, and external-content safety without querying GitHits evidence. Call once per session before other GitHits tools unless the guide is already in context. |
+| `quick_start` | none | Load the canonical guide for public GitHub/package search, grep, code, docs, examples, routing, and external-content safety without querying GitHits evidence. Plain MCP clients call it once per session before other GitHits tools; skip it when the loaded `githits-mcp` skill already carries the guide. |
 | `get_example` | `query`, `language?`, `license_mode?`, `format?` | Find canonical cross-project examples when no single target is the answer or target-scoped search came up short. For a known package or repository, use `search`, `docs_*`, or `code_*`. Defaults to markdown with source provenance and an optional `solution_id` for `feedback`; pass `format: "json"` for `{result, solution_id?}`. |
 | `search_language` | `query`, `format?` | Resolve a supported language name or alias for `get_example`; do not use it for source search. Defaults to one compact line per match; pass `format: "json"` for structured matches. |
 | `feedback` | `solution_id?`, `accepted`, `feedback_text?`, `tool_name?` | Submit feedback when a GitHits result or the overall experience was helpful, unhelpful, wrong, incomplete, slow, or confusing. Pass `solution_id` to rate an example or `tool_name` to identify a result. |
@@ -458,9 +461,11 @@ total-line response contract.
 
 The MCP server deliberately omits protocol-level `instructions`. Clients have
 handled that field as hidden guidance, privileged guidance, namespace metadata,
-or a prefix repeated on every tool. The `quick_start` tool exposes shared
-guidance once, on demand, while individual descriptions remain the source of
-truth for tool-specific routing, arguments, output, and recovery.
+or a prefix repeated on every tool. Plain MCP clients use the `quick_start`
+tool to expose shared guidance once, on demand. The loaded `githits-mcp` skill
+contains the same stable guide and therefore needs no normal bootstrap call;
+current tool descriptions remain the source of truth for tool-specific
+routing, arguments, output, and recovery.
 
 The concrete Codex failure was verified in August 2026. Codex PR
 [#21053](https://github.com/openai/codex/pull/21053) intentionally preserved
@@ -494,6 +499,13 @@ payload whose privilege, visibility, and repetition vary by host.
   Disabled or dormant reporting returns the public builder's exact baseline;
   public and remote servers never receive this block.
 
+The stable guide embedded in `skills/githits-mcp/SKILL.md` is an exact copy of
+`buildMcpQuickStart()` and is checked by `src/skills-packaging.test.ts`. The
+local experimental appendices from `buildLocalMcpQuickStart()` are not copied
+into the public skill; an exposed local `Experimental` descriptor or a material
+stale-snapshot mismatch is the bounded case where that client may call
+`quick_start` after loading the skill.
+
 The reporting contract is validated structurally in the focused instruction
 tests: one concise `accepted: false` report per distinct issue, exact enabled
 tool scope, redacted context, non-defect suppression, and no
@@ -665,7 +677,7 @@ See `docs/guidelines/TESTING.md` for the full testing pattern.
 | `packages/mcp/src/tools/shared.ts` | Shared MCP error/action helpers |
 | `packages/mcp/src/services/test-helpers.ts` | Mock service factories |
 | `packages/mcp/src/mcp/server.ts` | Transport-neutral MCP server construction and tool registration |
-| `packages/mcp/src/mcp/instructions.ts` | Canonical guide returned by `quick_start` |
+| `packages/mcp/src/mcp/instructions.ts` | Stable guide builder returned by `quick_start` and copied into the loaded `githits-mcp` skill |
 | `src/commands/mcp.ts` | CLI stdio startup, request-header mode setup, and TTY setup instructions |
 | `packages/core-internal/src/services/githits-service.ts` | REST API client for example search, languages, and feedback |
 | `packages/core-internal/src/services/code-navigation-service.ts` | Package/source service client for unified `search`, `search_status`, `code_files`, `code_read`, and `code_grep` |