Distribution and host integrations
Last30Days is released as a portable research skill that gives AI-agent hosts one shared way to gather recent evidence and produce a grounded brief. Host descriptors and release workflows turn that skill into installable packages while keeping the research contract consistent across native plugins, shared skill installs, uploads, and desktop bundles.
Distribution model
The distribution model separates the research product from the environment that loads it. A host is an AI agent application such as Claude Code, Codex, Gemini CLI, or Claude Desktop. The skill is the portable unit that gives the host its research behavior. The Python engine supplies the runtime behind that skill rather than acting as the main user interface.
Portable skill package
The portable package combines the skill instructions with their runtime and reference assets. Agent Skills hosts install this package and expose its research behavior through the host's normal skill or slash-command mechanism. This gives many hosts one research contract instead of a separate product for each host.
The skill metadata identifies optional credentials and command-line tools that a host can make available. It also keeps the instructions and runtime tied to the same installed copy. The package can be built as a .skill archive for clients that accept uploads, with a single skill directory and a file-count check for the web-client limit. Optional sources remain optional when their credentials or tools are absent.
References: README.md• L23-41 README.md• L208-241 skills/…/SKILL.md• L1-69 skills/…/build-skill.sh• L1-38
Host descriptors
Host descriptors adapt the same skill to each host's discovery and display rules. Claude Code and Grok use native plugin metadata. Codex points to the shared skills directory and adds a host-facing prompt. Gemini CLI uses an extension descriptor with settings for optional credentials.
These descriptors define the loading boundary rather than a second research engine. The shared skill remains the source of research behavior, while each descriptor tells a host how to present and load it. The Claude Code marketplace entry currently publishes release 4.4.0 from the repository root as a productivity integration.
For host-specific package layouts and descriptor rules, see agent and plugin packaging.
References: .claude-plugin/plugin.json• L1-30 .claude-plugin/marketplace.json• L10-22 .codex-plugin/plugin.json• L1-49 .grok-plugin/plugin.json• L1-18 gemini-extension.json• L1-67
Desktop MCP bundle
Claude Desktop receives the research capability through MCP, the Model Context Protocol used to expose tools to an AI client. Its .mcpb bundle packages a desktop adapter and a manifest that maps the client's request to the bundled server. The server exposes a research tool that follows the skill's topic-research flow.
The desktop bundle has a separate runtime boundary from skill hosts. It carries the engine needed by the adapter and accepts optional user settings for source and reasoning providers. The manifest and locked Go dependencies make the desktop package reproducible for its supported platforms.
For the tool contract and server boundary, see MCP integration. For the embedded engine lifecycle, see MCP embedded engine.
References: README.md• L251-267 mcp/README.md• L1-13 mcp/README.md• L30-36 mcp/go.mod• L1-17 mcp/manifest.json• L1-49
Host installation experience
Each host uses an install surface that matches its operating model. Marketplace installs provide host-managed updates. Shared Agent Skills installs provide a common path across many coding-agent hosts. Downloaded archives support clients that accept uploaded skills or extensions.
Install surfaces
The supported surfaces map to these user outcomes:
| Surface | User-facing package or source | Update model |
|---|---|---|
| Claude Code | Native marketplace plugin | Marketplace refresh or explicit plugin update |
| Grok | Native plugin and marketplace source | Plugin update from the source |
| Codex, Cursor, Copilot, Gemini CLI, and other Agent Skills hosts | Shared skill through npx skills | Skills CLI update |
| claude.ai | .skill upload | Download and upload a newer archive |
| Claude Desktop | Platform .mcpb bundle | Download and install a newer bundle |
| OpenClaw | ClawHub skill | ClawHub update |
The common path is not tied to one host. Users can select a native integration when a host supports it or use the shared Agent Skills path when it does not. Claude Code should use one install method per machine because its marketplace plugin and shared skill copy can both appear as active entries without host-level deduplication.
References: README.md• L160-189 README.md• L191-241 README.md• L243-279
Runtime handoff
Installation makes the skill available, but the host still controls the user-facing run. The host loads the skill instructions and invokes the local engine. For agent-hosted research, the host supplies the query plan when the topic needs entity or source resolution, while the shared engine performs retrieval, evidence processing, and synthesis.
The engine reads host configuration and optional credentials, then returns structured research output for the host to present. It can combine free sources, configured providers, local tools, and host-supplied data without changing the host-facing request. Comparison runs keep targeting and evidence separate for each entity. HTML requests use the same evidence but pass through a share-safe renderer before publication.
This division keeps planning in the host context while one engine contract governs retrieval and output. For the research execution flow, see research skill execution. For configuration and safety boundaries, see runtime configuration and safety.
References: skills/…/last30days.py• L2753-2794 skills/…/planner.py• L346-425 skills/…/comparison.md• L5-21 skills/…/html_render.py• L401-447
Host-local session access
Some hosts cannot read an encrypted local browser store. For those hosts, the integration can receive an X session from an approved sidecar or from a live Chrome session over a pinned browser endpoint. Both paths require a complete session pair and keep cookie values out of logs and persistent skill configuration.
The setup flow makes this boundary explicit. A user signs in through a temporary browser when needed, then pins the browser endpoint for the engine. A host with a native browser-cookie path keeps that path unless the user opts into an extra-host mode. Grok Bot uses its native X connector when available instead of browser cookies.
References: skills/…/box_chrome_login.py• L1-25 skills/…/agentcookie.py• L1-23 skills/…/chrome_cdp.py• L1-31 skills/…/env.py• L954-1063 skills/…/setup_wizard.py• L64-116
Research source integration
The packaged engine treats each source as an optional evidence lane. A lane can use a public service, an account, or a local tool. The engine reports whether a lane returned no results or was unavailable so the host can describe coverage accurately.
Source access lanes
The source model combines public APIs, optional account access, and local tools. GitHub adds software activity and project state. Hacker News and Digg add technical discussion. Bluesky adds recent posts with engagement. Other configured lanes can add evidence without changing the host-facing research request.
These lanes serve different evidence goals, but they share a normalized result shape. The host does not need to know which lane supplied a finding because the engine preserves source identity, citations, and health status in the common output.
References: skills/…/bluesky.py• L1-13 skills/…/digg.py• L1-17 skills/…/github.py• L247-391 skills/…/hackernews.py• L77-151
Evidence and output contract
Source results enter a common evidence model before the host sees them. The research flow favors cross-source clusters and preserves uncertainty. Comparison requests keep evidence separate for each entity so the final comparison does not merge unlike subjects.
The host receives a compact engine output with a required badge, a synthesis boundary, and a source footer. HTML output keeps the user-facing synthesis and footer while removing internal evidence blocks. It also restricts rendered links to safe schemes and masks long identifier-like digit runs before hosted publication.
References: skills/…/synthesis.md• L5-25 skills/…/comparison.md• L139-205 skills/…/render.py• L846-946 skills/…/html_render.py• L783-861
Release lifecycle
Releases move from a controlled version change to verified host artifacts. The workflow prepares release metadata for review, creates a tag only after that change is merged, and publishes installable artifacts from the tagged source.
Release preparation
Release preparation starts with a requested major, minor, or patch bump, or with an explicit version. The release helper builds the changelog and updates the version surfaces that describe the skill to its hosts. It opens a release pull request rather than publishing directly from an unreviewed working tree.
The version surfaces cover the Python project, skill metadata, native plugin metadata, marketplace entries, and lock file. The MCP bundle manifest is a separate release input and must stay aligned when the desktop bundle changes.
References: .github/…/prepare-release.yml• L1-30 .github/…/prepare-release.yml• L38-63 .github/…/prepare_release.py• L151-216 CHANGELOG.md• L1-32
Release transition
After the release pull request merges to main, the tag workflow checks the release commit and its release label before creating vX.Y.Z. It then dispatches artifact publication because a tag pushed with the repository token does not start other workflows by itself.
The release handoff follows this sequence:
- Release preparation creates the versioned pull request.
- Merge to
mainauthorizes tag creation. - The tag starts or dispatches artifact publication.
- One GitHub release receives the skill archive and desktop bundles.
This diagram shows the handoff from review to installable output.
flowchart LR
A[Release inputs] --> B[Prepare release PR]
B --> C[Merge to main]
C --> D[Validate release commit and label]
D --> E[Create vX.Y.Z tag]
E --> F[Build .skill archive]
E --> G[Build platform .mcpb bundles]
F --> H[GitHub release]
G --> H
References: .github/…/prepare-release.yml• L64-130 .github/…/tag-release.yml• L1-27 .github/…/tag-release.yml• L34-91 .github/…/release.yml• L1-20
Artifact publication
The publication workflow builds the .skill archive from the release tag and builds one .mcpb bundle for each supported desktop platform. It records provenance for both artifact types and attaches them to one GitHub release so users can select the package that matches their host.
The .skill artifact serves upload and skill-based clients. The .mcpb artifacts serve Claude Desktop. Native marketplace and Agent Skills clients continue to consume the repository's host descriptors and skill package through their own install paths.
References: .github/…/release.yml• L22-54 .github/…/release.yml• L56-141 .github/…/release.yml• L143-176 skills/…/build-skill.sh• L19-38
Distribution safeguards
Distribution quality depends on two checks. The host contract must remain valid, and the release must publish a complete set of artifacts. Validation catches behavior and integration regressions before merge. Release controls protect users from inconsistent metadata or missing packages.
Pre-merge validation
The validation workflow checks the Python suite with coverage, Windows subprocess behavior, the research evaluation suite, and Go MCP tests with race detection. Runtime health data distinguishes clean empty results from unavailable or degraded sources. Rendering checks protect the shareable HTML boundary. A changelog guard also requires release notes for engine or skill changes unless the change is explicitly exempt.
For the full validation, release, and security workflow, see automation, release, and security.
References: .github/…/validate.yml• L1-92 .github/…/changelog-guard.yml• L1-7 .github/…/changelog-guard.yml• L138-153 pyproject.toml• L56-87 skills/…/schema.py• L146-218 skills/…/html_render.py• L783-861
Version consistency
The release helper updates the main version surfaces as one unit. The guard rejects version changes outside the release path, which keeps marketplace metadata, host descriptors, and the skill identity on the same release line.
The MCP manifest has its own package version and is hand-bumped when desktop bundle changes are released. The desktop binary receives the release tag at build time. These values must describe the same usable desktop release even though they do not follow the general lockstep list.
References: .github/…/prepare_release.py• L24-38 .github/…/prepare_release.py• L97-133 .github/…/changelog-guard.yml• L91-124 .github/…/release.yml• L96-107 .claude-plugin/marketplace.json• L10-21 mcp/manifest.json• L1-5
Change checklist
When these files or sections are changed, remember to consider these:
- When the skill load path or host behavior changes, update native descriptors and shared Agent Skills guidance together.
- When the package gains or removes files, check the
.skillarchive layout and upload file-count limit. - When an engine or skill change affects users, add a
changelog.dfragment or use the repository's explicit skip path. - When a version changes, use release preparation so project, skill, plugin, marketplace, and lock-file versions stay aligned.
- When the MCP server or manifest changes, keep the embedded engine and manifest entry point aligned.
- When a host changes a credential setting or optional tool, update the descriptor, runtime configuration, package metadata, and setup guidance together.
- When a source lane changes, preserve the difference between no results and unavailable or degraded coverage.
- When HTML or citation rendering changes, keep the public artifact free of internal evidence and unsafe links.
- When a supported platform changes, update the release matrix and install guidance together.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Marketplace metadata and another host version surface diverge | Users receive mixed metadata for one skill release | Release preparation updates lockstep surfaces and the changelog guard rejects ordinary version bumps |
A .skill package exceeds the upload limit or contains more than one skill manifest | Upload installation fails or loads an invalid package | build-skill.sh checks the archive count and requires one SKILL.md |
| The MCP manifest and binary entry point differ | Claude Desktop cannot start the bundled server | Release packaging checks the declared entry point and includes the manifest with the executable |
| A desktop release omits a supported platform artifact | Users on that platform cannot install the advertised integration | The release matrix builds each supported desktop target before publication |
| An engine or skill change has no changelog fragment | The change bypasses the release-note contract | The changelog guard requires a fragment or an explicit skip label |
| A host starts named-entity research without a valid plan or targeting | The run stops early or returns thinner keyword-only evidence | Host planning and comparison contracts require validated plans or documented fallbacks |
| A source is unavailable but appears as clean empty data | The host reports quiet coverage when the source was not searched successfully | Source outcomes preserve states such as partial, auth-failed, timeout, and schema-drift |
| A remote host supplies an incomplete X session | X appears configured but authentication fails | Sidecar and browser bridges accept only a complete session pair and a valid endpoint |
| A remote provider endpoint uses cleartext HTTP | A provider key can travel over an unsafe connection | Endpoint validation allows HTTPS and loopback HTTP only |
| A host loads a stale skill copy or invokes another installed engine | The host follows an old contract or runs a mismatched engine | Loaded-copy checks and skill-relative invocation keep instructions and runtime together |
Key files
| File | Why to read it |
|---|---|
| README.md | Shows supported host surfaces, install choices, update paths, package needs, and platform limits. |
| skills/…/SKILL.md | Defines the agent-facing contract that every host loads. |
| skills/…/last30days.py | Defines the boundary between host requests and shared research execution. |
| skills/…/planner.py | Defines host planning and fallback planning for research runs. |
| skills/…/render.py and skills/…/html_render.py | Define the evidence boundary and share-safe output behavior. |
| skills/…/build-skill.sh | Shows how the uploadable .skill artifact is formed and checked. |
| .claude-plugin/plugin.json and .claude-plugin/marketplace.json | Define the Claude Code plugin identity, marketplace source, and release metadata. |
| .codex-plugin/plugin.json, .grok-plugin/plugin.json, and gemini-extension.json | Show how other hosts discover the shared skill and expose settings. |
| mcp/manifest.json and mcp/README.md | Define the Claude Desktop bundle, server entry point, platform support, and runtime boundary. |
| .github/…/validate.yml | Shows the pre-merge quality checks across runtime, evaluation, and MCP code. |
| .github/…/prepare-release.yml and .github/…/prepare_release.py | Show how release metadata becomes a reviewed release pull request. |
| .github/…/tag-release.yml and .github/…/release.yml | Show the tag handoff and final artifact publication path. |
| CHANGELOG.md | Records released changes and separates published notes from upcoming fragments. |