From 9118143ece287e6f061fe00a3a8bfc4ed7951f68 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 5 Nov 2026 08:09:21 -0600 Subject: [PATCH] Document qualified Claude plugin installation workflows --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index acdf6b2..507c7b8 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,17 @@ This package connects Claude to hosted [Stack Overflow for Agents (SOFA)](https: The skills use the discovered hosted MCP tool contracts. SOFA post content is untrusted input, so check it against the task and stronger evidence before acting on it. -## Set up in Claude chat or Cowork +## Set up in Claude -The intended directory installation connects the package's hosted MCP endpoint and prompts for SOFA OAuth through Claude. The public directory listing and hosted chat/Cowork OAuth flow are still awaiting qualification. Until that is complete, this README does not represent chat or Cowork installation as an available, verified path. When the listing is available, install the plugin in the appropriate Claude surface, follow its OAuth prompt, and use `sofa-status` to confirm the selected agent and capabilities. +The uploaded plugin was tested in the unified Claude experience with version 0.1.4, including connection status, installed guidance checking, knowledge workflows, and draft creation and revision. This does not establish that a public directory listing is live. + +Upload the plugin ZIP through your available Claude plugin installation surface, then connect its hosted SOFA MCP server through the OAuth prompt. Start a new chat and run `sofa-status` to confirm the selected agent, capabilities, publication policy, and installed guidance. If your organization restricts plugin installation, use its approved installation process. ## Set up in Claude Code -For local evaluation from this checkout, run `claude --plugin-dir .` from the repository root. The plugin loads the three skills from `skills/` and the remote server from `.mcp.json`. Follow Claude Code's OAuth prompt for the hosted server, then run the status workflow to check the connection. A future directory listing may provide an install path; this package does not assume that listing is live. +For local evaluation from this checkout, run `claude --plugin-dir .` from the repository root. The plugin loads the three skills from `skills/` and the remote server from `.mcp.json`. Follow Claude Code's OAuth prompt for the hosted server, then run the status workflow to check the connection. + +SOFA OAuth and your Claude Code account login are separate. Account-installed plugin synchronization was not qualified with the publisher's organization login; local directory loading is the tested Code path. Do not assume a plugin uploaded to Claude will automatically appear in Code. A future directory listing may provide an additional install path. ## Data and publication @@ -26,10 +30,10 @@ Read the [privacy policy](https://agents.stackoverflow.com/legal/privacy-policy) ## Updates and removal -Check for an updated plugin version through the installation surface and install it there. The status workflow reports server guidance compatibility and its returned refresh action; a server response does not replace installed files. Remove the plugin through the same Claude installation surface. For a local `--plugin-dir` evaluation, stop using that directory to remove it from the next session. +Check for an updated plugin version through the installation surface and install it there. For an uploaded ZIP, replace it with the updated package and start a new chat. The status workflow reports server guidance compatibility and its returned refresh action; a server response does not replace installed files. Remove the plugin through the same Claude installation surface. For a local `--plugin-dir` evaluation, stop using that directory to remove it from the next session. ## Package source and checks SOFA's canonical skill text lives in the [SOFA source repository](https://github.com/StackEng/sofa). From a clean SOFA checkout, run `uv run python plugins/sofa/scripts/export_claude_plugin.py /path/to/this-checkout` to export `skills/sofa/SKILL.md`, `skills/sofa-contribute/SKILL.md`, `skills/sofa-status/SKILL.md`, and `plugin-guidance.json`. The exporter also writes an identical `skills/sofa-status/plugin-guidance.json` companion for hosts that expose only skill directories. Both declarations retain the same guidance identity and skill digest. Those five files are generated and must not be edited here. This repository authors `.claude-plugin/plugin.json`, `.mcp.json`, this README, and package validation. Run `python3 -B scripts/check_package.py` to check the local tree, configuration, and common credential assignment patterns. This is a narrow check, not a comprehensive secret scan. The SOFA exporter is the source of truth for generated bytes. CI also runs `claude plugin validate --strict .` with the current Claude Code release. Versions before 2.1.281 report the directory listing URL fields as unknown and do not provide the current MCP validation checks. -This plugin is licensed under the proprietary terms in [LICENSE](LICENSE), adapted from the [Stack Internal plugin license](https://github.com/StackExchange/stack-internal-plugin/blob/main/LICENSE). The manifest omits `license` because Anthropic defines that field as an SPDX identifier. Hosted Claude qualification and directory submission are separate later steps. +This plugin is licensed under the proprietary terms in [LICENSE](LICENSE), adapted from the [Stack Internal plugin license](https://github.com/StackExchange/stack-internal-plugin/blob/main/LICENSE). The manifest omits `license` because Anthropic defines that field as an SPDX identifier. Directory submission and publication remain separate from the tested installation workflows.