Introducing a new way to review your PRs.

Read the announcement

mvanhorn / last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

View on GitHub

21 documents · Updated Nov 20, 2026

docs / agent-plugin-packaging

Agent and plugin packaging

Last30Days is shipped as one shared research skill with host-specific descriptors around it. The skill defines the /last30days command, its research contract, and its result boundary. Plugin, marketplace, and agent records give supported coding-agent environments the identity and entry points needed to install and run that same capability. This page is a child of Distribution and host integrations and relates to Automation, release, and security and Research skill execution.

Packaging model

Shared skill contract

The shared skill contract is the host-neutral description of Last30Days. It defines the research goal, the tools an agent may use, the runtime needs, optional credentials, and the rules for producing a result. It also defines setup gates, source checks, trusted save-directory resolution, and route-specific research guidance. The skill directory packages this contract with the runtime and supporting assets.

The manifest tells hosts which executables and optional environment values support the skill. This lets a host install the common capability without making every source or credential a hard requirement. The package keeps research behavior in this shared contract. A host selects and presents the skill, while the skill controls the research flow, source targeting, and output rules.

The contract binds engine calls to the directory that supplied the loaded SKILL.md. An agent must use that directory instead of searching for another installed copy. This keeps the instructions and engine from different releases from being paired by mistake.

References: skills/…/SKILL.md• L1-70 skills/…/SKILL.md• L75-112 skills/…/SKILL.md• L122-152 skills/…/SKILL.md• L228-261

Host entry points

Host entry points adapt the shared skill to the discovery and install rules of each coding-agent environment. Plugin and marketplace records identify the product for host catalogs. Agent metadata supplies the display and invocation information that an agent-facing catalog needs.

The descriptors share one product identity and release version. Their descriptions may differ because each host presents skills in a different way. The Claude and Codex plugin descriptors now identify release 4.4.0; the Codex descriptor also maps the host to the shared skills/ directory and defines the host-facing display, capability, and prompt settings. These records do not create separate research products.

Host surfacePackaging role
Claude pluginPlugin identity and marketplace discovery
Codex pluginSkill-root mapping and host interface metadata
Grok pluginSkill-root mapping and host interface metadata
Gemini CLI extensionExtension identity and user configuration surface
OpenAI agent catalogDisplay text, default prompt, and invocation policy

References: .claude-plugin/plugin.json• L1-30 .claude-plugin/marketplace.json• L1-24 .codex-plugin/plugin.json• L1-49 .grok-plugin/plugin.json• L1-18 .grok-plugin/marketplace.json• L1-25 gemini-extension.json• L1-67 skills/…/openai.yaml• L1-8

Package assembly

Package assembly turns the skill directory into an installable artifact for hosts that accept a skill archive. The build process creates one top-level last30days/ directory and checks that the archive has a bounded file count and one clear SKILL.md entry contract.

The directory carries the runtime, reference material, and bundled assets. The .skillignore file marks content that install-time security scans must omit. It does not define the complete archive, so changes to the build process or skill directory can change what ships without changing the scan boundary.

This diagram shows how the shared contract and host descriptors lead to an installed research capability.

flowchart LR
    A[Shared skill contract] --> B[Skill runtime and assets]
    B --> C[Skill archive]
    A --> D[Host descriptors]
    D --> E[Host installation]
    C --> E
    E --> F[Agent session]
    F --> G[Research request]

References: skills/…/build-skill.sh• L1-38 skills/…/.skillignore• L1-13 skills/…/SKILL.md• L1-70

Host lifecycle

Session-start hooks

The Claude plugin can run a configuration check when a session starts. The check prepares the local memory area and reports setup, source access, and recent-run state before research begins. This gives the agent an early status instead of a later failure during a topic run.

The check uses the same trust rules as the runtime. Process settings have priority. Global settings may allow project settings, but a project cannot authorize its own configuration. The hook also checks secret-file permissions and key presence without printing secret values.

References: hooks/hooks.json• L1-15 hooks/…/check-config.sh• L4-23 hooks/…/check-config.sh• L103-189 hooks/…/check-config.sh• L194-233

Credential settings

Host settings expose optional credentials as inputs to source capabilities. Gemini marks API keys and browser credentials as sensitive. The skill metadata separates required executables from optional environment values, so a new installation can run with a basic source set and gain more coverage as the user configures more sources.

The settings do not create package variants. Missing optional credentials reduce source coverage. They do not change the skill identity. The skill can use keyless sources and add coverage when the user configures more providers.

References: skills/…/SKILL.md• L12-40 skills/…/SKILL.md• L228-257 gemini-extension.json• L5-65

Version identity

All packaging surfaces describe the same Last30Days release. The Claude and Codex plugin descriptors now identify release 4.4.0; the other host manifests and project version complete the release identity.

Marketplace records repeat the version because they describe what a catalog offers. Release preparation must update these records with the other package surfaces. The related Automation, release, and security page describes that wider release process.

References: .claude-plugin/plugin.json• L1-4 .claude-plugin/marketplace.json• L10-15 .codex-plugin/plugin.json• L1-4 pyproject.toml• L1-7 .github/…/prepare_release.py• L22-38 .github/…/prepare_release.py• L93-165 .github/…/read_manifest_version.py• L18-38 tests/test_plugin_contract.py• L70-106

Packaging contracts

Skill-root mapping

Plugin descriptors point hosts to the shared skill root instead of a duplicate skill copy. This mapping connects host installation to the contract and its runtime. If the skill moves, the descriptors and archive layout must move with it or installation can succeed without a usable /last30days entry point.

References: .codex-plugin/plugin.json• L30-49 .grok-plugin/plugin.json• L13-18 tests/test_plugin_contract.py• L23-29 tests/test_plugin_contract.py• L47-51

Descriptor identity

Marketplace records tell a host where to find Last30Days and what release it offers. The Claude record uses a repository-local source. The Grok record uses the public repository URL. This difference changes discovery only. It does not change the shared skill.

References: .claude-plugin/marketplace.json• L10-22 .grok-plugin/marketplace.json• L8-23 tests/test_plugin_contract.py• L31-68

Agent output boundary

The agent-facing output contract gives hosts a stable structured view of research. Agent mode uses a report form for workflows, while an explicit machine-readable request uses --emit=json and passes engine output without extra prose. The output preserves per-source states so a host can tell the difference between no matches and an unavailable or rate-limited source.

This boundary matters because hosts can consume structured results even when their prompts and visible presentation differ. A change to this shape is a host contract change, not only an internal data change.

References: skills/…/SKILL.md• L154-186 skills/…/SKILL.md• L205-218 tests/…/agent_export_v1.json• L1-55 tests/test_agent_export.py• L165-183

Change checklist

When these files or sections are changed, remember to consider these:

  • A release version change must reach the project version, the skill front matter, all host manifests, and the marketplace records. The release helper and manifest reader define this lockstep boundary.
  • A move under skills/last30days/ must preserve the host skill-root mappings and the archive's single top-level last30days/ layout.
  • A change to the loaded-skill path rule must keep engine calls bound to the same SKILL.md directory. Do not reintroduce host-specific stale-copy discovery.
  • A change to the skill's executable, invocation rules, or optional environment contract must stay aligned with host settings and startup status reporting.
  • A new bundled file must fit the archive file-count limit and the .skillignore security-scan boundary.
  • A change to structured agent output must preserve source-status meanings and the export schema consumed by agent hosts.

Important failure modes

TriggerConsequenceGuard
A Claude session loads an older marketplace copy instead of the loaded skill's current directoryThe agent follows old instructions and can run an older engineKeep the stale-clone check and bind engine calls to the loaded SKILL.md directory
One manifest or marketplace record keeps an old versionA host can display or install a release that does not match the shared skillUse lockstep release preparation and version contract checks
A descriptor points outside the shared skill rootInstallation succeeds but the host cannot resolve /last30daysPreserve the skill-root mapping and test it from the repository root
The archive has too many files or lacks one clear SKILL.mdA host rejects the upload or cannot identify the skill contractRun the archive build checks before upload
A secret field is exposed as normal host configurationCredential values can appear in host UI or stored settingsMark credential fields as sensitive
A source failure loses its status in the structured exportThe host can report quiet evidence when the source was unavailablePreserve explicit per-source states such as no-results, rate-limited, and unreachable

Key files

FileWhy to read it
skills/…/SKILL.mdDefines the shared skill identity, invocation contract, source routes, runtime needs, security limits, and agent output modes
skills/…/openai.yamlShows agent-catalog presentation and invocation policy
skills/…/build-skill.shDefines the upload archive shape and integrity checks
skills/last30days/.skillignoreDefines the security-scan boundary for install-time checks
.claude-plugin/plugin.jsonDescribes Claude plugin identity and release metadata
.claude-plugin/marketplace.jsonDescribes Claude marketplace discovery and the offered release
.codex-plugin/plugin.jsonMaps Codex to the shared skill root and interface metadata
.grok-plugin/plugin.jsonMaps Grok to the shared skill root
.grok-plugin/marketplace.jsonDescribes Grok marketplace discovery and its remote source
gemini-extension.jsonDefines Gemini extension identity and sensitive configuration fields
hooks/hooks.jsonConnects session start to the configuration status hook
hooks/…/check-config.shReports startup state while enforcing configuration trust boundaries
.github/…/prepare_release.pyUpdates release identity across packaging surfaces
tests/test_plugin_contract.pyProtects host mappings, marketplace sources, schema shape, and version lockstep
tests/test_agent_export.pyProtects the structured agent-result boundary and source outcome mapping