docs(crm-agent): SKILL.md — strip host/project-specific accretion#73
Merged
Conversation
…igned-for The "Tested against" list claimed 4 hosts (Claude Desktop, VS Code Copilot MCP, in-repo agent, Copilot Studio). In reality only the in-repo agent has been verified end-to-end. The other 3 are aspirational MCP-spec compliance. Today we also empirically verified Claude Code works — but only via the auth-injecting proxy added in PR #71, not via `.mcp.json` directly, because Claude Code's `--header` Bearer support is static and our tokens are short-lived. Restructure to distinguish two categories: - "Verified end-to-end": the in-repo agent + Claude Code (via local proxy). Names the proxy by reference for hosts with the same token-lifecycle gap. - "Designed-for, not yet verified by us": Claude Desktop, VS Code Copilot MCP, Copilot Studio. All three accept static Bearer via `.mcp.json` directly; refresh discipline is on the customer. Also explicitly states the implicit precondition that was always true but never stated: hosts must be able to attach `Authorization: Bearer <user-jwt>` to every request. The bundle's only interface with the host is `.mcp.json`; how the host sources a JWT is host-specific (and is the gnarly part for hosts whose token model isn't a great fit). 32 tests pass. No code/config change. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…expanded) The "Compatibility honest" change in this PR's first commit was the right direction but too narrow. SKILL.md had been accreting more than just one overclaim — multiple sections were host-specific or project-specific in a way that breaks the "host-portable bundle" promise from ADR 0009. Removed (project / host specific noise): - "Single-source note" callout about in-repo agent + SkillsProvider — external customers don't care that OUR agent consumes this bundle. - "Setup" 3-step section enumerating Claude Desktop / VS Code / Custom agent wiring — those belong in each host's own MCP docs. The 1-line "edit .mcp.json + wire per host docs" is enough. - "Reference deployments: Bicep / func start / run_mcp_server_local.py" paragraph — pure project-specific (already documented in docs/deployment/walkthrough-zh.md and llm-foundry-zh.md). - "Compatibility" section listing verified-by-us hosts (Claude Code via proxy, etc.) — the "in this repo" framing falls apart the moment the bundle is dropped into a non-this-repo context. - Frontmatter `compatibility:` field's enumeration of named hosts. - "Further reading" link to "main repo docs/" — bundle shouldn't reach back into specific project layout. Kept (host-agnostic core): - Frontmatter (with generalized `compatibility:` text). - 2-line intro: what the skill does + how to wire (.mcp.json + host docs). - Available tools table — the contract. - Rating values / dates / FIELD_REFERENCE pointer — tool data the LLM uses. - SOP § 1-4 (name resolution, destructive confirm, RLS, error fidelity). - 3 Example dialogues. - references/FIELD_REFERENCE.md link. Test casualty: removed `test_skill_md_references_adr_0009` since we deliberately removed the ADR 0009 reference (it was the project-specific "single-source note"). The host-neutrality test (`test_skill_md_setup_is_host_neutral`) remains — its docstring no longer mentions ADR 0009 either. Net: 119 → 95 lines (-20%). 31 affected tests pass. Project-specific content all moved (or already lives) in the right docs: - Setup mechanics → docs/deployment/walkthrough-zh.md, llm-foundry-zh.md - Claude Code via proxy → llm-foundry-zh.md "本地 REPL" §4 - ADR 0009 single-source rationale → docs/adr/0009-... Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
carvychen
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Started as a focused fix to one overclaim in the Compatibility section. After review, the bigger issue surfaced: SKILL.md had accreted host-specific and project-specific content that violates the host-portable promise from ADR 0009. A skill bundle dropped into Claude Desktop or any other MCP host should not contain "Reference deployments: Bicep / run_mcp_server_local.py" or "Verified by us in Claude Code via proxy" — those are project-internal facts.
This PR strips that accretion back to the host-agnostic core.
Removed
docs/deployment/walkthrough-zh.md+llm-foundry-zh.md.compatibility:enumerating named hostsKept (host-agnostic)
references/FIELD_REFERENCE.mdlink (still inside the bundle).Net: 119 → 95 lines (-20%).
Where the removed content went
docs/deployment/walkthrough-zh.md+llm-foundry-zh.md(already there)llm-foundry-zh.md"本地 REPL" §4 (already there from PR #71)docs/adr/0009-skill-as-sop-single-source.md(canonical home)Test plan
test_skill_md_references_adr_0009— that assertion protected the project-specific "Single-source note" we deliberately deletedtest_skill_md_setup_is_host_neutral(the "no Lenovo" test) remainssrc/mcp_server/__init__.py(7 tools, unchanged)🤖 Generated with Claude Code