# Model clients

> Per-harness install patterns: Claude Code marketplace, npx skills -a targets, Codex/Cursor/Gemini, Hermes, OpenClaw, and stale-install avoidance.

- Repository: mvanhorn/last30days-skill
- GitHub: https://github.com/mvanhorn/last30days-skill
- Human docs: https://grok-wiki.com/public/docs/mvanhorn-last30days-skill-50b5421a8cca
- Complete Markdown: https://grok-wiki.com/public/docs/mvanhorn-last30days-skill-50b5421a8cca/llms-full.txt

## Source Files

- `README.md`
- `CONFIGURATION.md`
- `HERMES_SETUP.md`
- `.claude-plugin/marketplace.json`
- `.agents/plugins/marketplace.json`
- `gemini-extension.json`
- `skills/last30days/agents/openai.yaml`

---

---
title: "Model clients"
description: "Per-harness install patterns: Claude Code marketplace, npx skills -a targets, Codex/Cursor/Gemini, Hermes, OpenClaw, and stale-install avoidance."
---

The last30days Agent Skills package (`skills/last30days/`) installs into harness-specific skill directories; each host loads `SKILL.md` and invokes `scripts/last30days.py` from that install via `SKILL_DIR` (the directory containing the `SKILL.md` the model read). Distribution is provider-neutral: one skill tree, multiple install surfaces, no requirement for a single model vendor.

## Harness vs engine

| Layer | Role | Canonical artifact |
| --- | --- | --- |
| **Harness** | Agent runtime that exposes the slash command or skill invocation | Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenClaw, 50+ Agent Skills hosts |
| **Skill** | Prose contract + flags the model must pass | `skills/last30days/SKILL.md` |
| **Engine** | Python research pipeline | `skills/last30days/scripts/last30days.py` |

```mermaid
flowchart LR
  subgraph hosts [Harnesses]
    CC[Claude Code marketplace]
    AS[npx skills add -a targets]
    HM[Hermes skills install]
    OC[OpenClaw clawhub]
  end
  subgraph install [Install tree]
    SM[SKILL.md]
    PY[scripts/last30days.py]
  end
  hosts --> SM
  SM --> PY
```

When a reasoning harness runs `/last30days`, the host model is the planner and synthesizer; external reasoning API keys are only required for headless runs (cron, watchlist, direct CLI without a host). See the configuration reference for provider priority.

## Install matrix

Current release version is **3.3.1** (aligned across `skills/last30days/SKILL.md`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and `gemini-extension.json`).

| Harness / surface | Install command | Update | Typical on-disk path |
| --- | --- | --- | --- |
| **Claude Code** (recommended) | `/plugin marketplace add mvanhorn/last30days-skill` then `/plugin install last30days@last30days-skill` | Auto via marketplace; `claude plugin update last30days@last30days-skill` | `~/.claude/plugins/cache/last30days-skill/last30days/{version}/skills/last30days/` |
| **Agent Skills hosts** (Codex, Cursor, Copilot, Gemini CLI, Windsurf, Cline, Continue, Roo, OpenCode, Goose, …) | `npx skills add mvanhorn/last30days-skill -g` | `npx skills update last30days -g` | `~/.codex/skills/last30days`, `~/.agents/skills/last30days`, or host-specific dir |
| **claude.ai** (web) | Download `last30days.skill` from [latest release](https://github.com/mvanhorn/last30days-skill/releases/latest/download/last30days.skill); upload in Settings → Capabilities → Skills | Re-download and re-upload | Hosted skill bundle (not a local tree) |
| **Hermes** | `hermes skills install mvanhorn/last30days-skill --force` | Same command | `~/.hermes/skills/research/last30days/` |
| **OpenClaw** | `clawhub install last30days-official` | `clawhub update last30days-official` | `~/.openclaw/skills/last30days/` (per OpenClaw layout) |
| **Developer live-edit** | `ln -sfn "$PWD/skills/last30days" ~/.agents/skills/last30days` (from repo root) | `git pull` in the repo | Symlink to working tree |

<Note>
Claude Code does **not** dedupe across install methods. If both the marketplace plugin and an `npx skills` copy are active, `/last30days` can appear twice in the command picker. Pick one install method per machine.
</Note>

## Claude Code marketplace

Claude Code is the most common harness. The marketplace manifest lives at `.claude-plugin/marketplace.json` (plugin name `last30days`, source `./`). Plugin metadata is in `.claude-plugin/plugin.json`; Claude Code auto-discovers `skills/*/SKILL.md` without a `"skills": ["./"]` entry (that pattern was removed after path-escape errors on newer Claude Code builds).

<Steps>
<Step title="Add marketplace and install plugin">

```text
/plugin marketplace add mvanhorn/last30days-skill
/plugin install last30days@last30days-skill
```

</Step>
<Step title="Force an update when needed">

```text
claude plugin update last30days@last30days-skill
```

Or in-session: `/plugin update last30days` then `/reload-plugins`.

</Step>
<Step title="Verify cached version">

```bash
cat ~/.claude/plugins/cache/last30days-skill/last30days/*/.claude-plugin/plugin.json | grep version
```

Expect `"version": "3.3.1"` (or your target release).

</Step>
</Steps>

Optional Agent Skills path on Claude Code (coexists with marketplace — avoid unless you intend dual installs):

```bash
npx skills add mvanhorn/last30days-skill -g -a claude-code
```

Invocation: `/last30days <topic>` (user-invocable skill; `argument-hint` documents example topics).

## Agent Skills CLI (`npx skills`)

Canonical install for Codex, Cursor, GitHub Copilot, Gemini CLI, and [50+ hosts](https://agentskills.io) via [vercel-labs/skills](https://github.com/vercel-labs/skills).

<CodeGroup>

```bash title="Global (recommended)"
npx skills add mvanhorn/last30days-skill -g
```

```bash title="Project-local"
npx skills add mvanhorn/last30days-skill
```

```bash title="Target specific harnesses"
npx skills add mvanhorn/last30days-skill -g -a codex
npx skills add mvanhorn/last30days-skill -g -a cursor
npx skills add mvanhorn/last30days-skill -g -a gemini-cli
npx skills add mvanhorn/last30days-skill -g -a codex -a cursor
```

</CodeGroup>

| Flag | Effect |
| --- | --- |
| `-g` | User-global install (available across projects) |
| `-a <harness>` | Target one or more harness adapters (`codex`, `cursor`, `gemini-cli`, `claude-code`, `github-copilot`, `windsurf`, `cline`, `continue`, `roo`, `aider-desk`, `opencode`, `goose`, …) |
| (no `-a`) | Installs for whichever harness `npx skills` detects |

Maintenance:

```bash
npx skills update last30days -g    # this skill only
npx skills update -g               # all global skills
npx skills list -g
npx skills remove last30days -g
```

<Warning>
`npx skills add` copies into `~/.agents/skills/last30days/` and symlinks per-host dirs where supported. That copy is **frozen at install time** — repo edits do not propagate until you re-run `npx skills add mvanhorn/last30days-skill -g` (or use a dev symlink). Contributors syncing a working tree use `npx skills add . -g -y` from the repo root.
</Warning>

### Codex

The `.codex-plugin/` scaffold was removed (v3.3.0). Codex users install via `npx skills add` or manual copy to `~/.codex/skills/last30days/`. Agent metadata for Codex-style hosts is in `skills/last30days/agents/openai.yaml` (`display_name`, `default_prompt`, `allow_implicit_invocation`).

Historical note: early Codex docs referenced `$last30days`; current installs follow the host’s skill/slash-command naming.

### Cursor, Copilot, Windsurf, and other `-a` targets

Same `npx skills add` flow with `-a <harness>`. Invocation is the host’s skill mechanism (slash command or skill picker per client). Do not pass shell pipes or flags through the slash form — express intent in natural language and let the model map to engine flags, or call the engine directly for scripting.

### Gemini CLI

README no longer documents a separate native-extension install path; use `npx skills add … -a gemini-cli`. The repo still ships `gemini-extension.json` (version **3.3.1**) listing optional env vars (`SCRAPECREATORS_API_KEY`, `BRAVE_API_KEY`, `XAI_API_KEY`, cookie vars, etc.) for extension-style configuration if your Gemini setup consumes that manifest.

## claude.ai (web)

Web Claude does not use the marketplace cache. Package a uploadable bundle from source:

```bash
bash skills/last30days/scripts/build-skill.sh   # from repo root; requires clean git tree
```

Produces `dist/last30days.skill` (zip with top-level `last30days/`, ≤200 files). Upload via [claude.ai Settings → Capabilities → Skills](https://claude.ai/settings/capabilities). Enable **Code execution and file creation** or skills will not run.

## Hermes

Hermes uses its own installer (not `npx skills`):

```bash
hermes skills install mvanhorn/last30days-skill --force
```

Deploys to `~/.hermes/skills/research/last30days/`. Invoke as:

```text
last30days "your research topic"
last30days "best mechanical keyboards 2025" --search=reddit,youtube
```

Prerequisites: Python 3.12+, optional `yt-dlp`. Diagnose from the install dir:

```bash
cd ~/.hermes/skills/research/last30days
python3.12 scripts/last30days.py --diagnose
```

Developer live-edit: symlink `skills/last30days` into `~/.hermes/skills/research/last30days` (see `HERMES_SETUP.md`).

## OpenClaw

OpenClaw distributes via ClawHub, not the public GitHub marketplace:

```bash
clawhub install last30days-official
clawhub update last30days-official
```

`SKILL.md` frontmatter includes `metadata.openclaw` (required bins `node`, `python3`, optional env keys, `clawhub` tag). SKILL contract documents a failure mode where models improvised `for dir in …` path discovery and hit a stale `~/.openclaw/skills/last30days/` engine — use `SKILL_DIR` from the loaded `SKILL.md`, not ad hoc directory walks.

## SKILL_DIR binding (all harnesses)

Every engine invocation must use the install that loaded `SKILL.md`:

```bash
SKILL_DIR="<absolute path of the directory containing the SKILL.md you Read>"
"${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" "<topic>" --emit=compact ...
```

Valid examples from the skill contract:

- `~/.claude/skills/last30days`
- `~/.codex/skills/last30days`
- `~/.claude/plugins/cache/last30days-skill/last30days/3.3.1/skills/last30days`
- `~/.agents/skills/last30days` (npx global copy)
- Repo checkout `…/skills/last30days`

If `scripts/last30days.py` is missing under `SKILL_DIR`, the install is broken or the model substituted the wrong path.

Badge version resolution: per-harness installs may lack `.claude-plugin/plugin.json`; the engine falls back to `SKILL.md` frontmatter `version` (see `scripts/lib/render.py`).

## Stale-install avoidance

### Claude Code marketplace clone (STEP 0)

`~/.claude/plugins/marketplaces/last30days-skill/` is a git clone Claude Code can restore to `origin/main` on session start. It may lag the **versioned cache** under `~/.claude/plugins/cache/last30days-skill/last30days/{version}/`.

`SKILL.md` **STEP 0** instructs the model: if the loaded path contains `/.claude/plugins/marketplaces/` and a newer cache `SKILL.md` exists, stop and re-read from the cache before proceeding. Documented impact: stale `--help` missed flags such as `--competitors` and broke comparison workflows.

Cache layout may be nested (`{version}/skills/last30days/SKILL.md`) or flat (`{version}/SKILL.md`); STEP 0 resolves whichever exists.

<Check>
Other paths (`~/.codex/skills/`, `~/.agents/skills/`, npx install dirs, repo checkouts) are valid load points — STEP 0 does not force a cache hop on those paths.
</Check>

### Frozen `npx skills` copy

Re-run `npx skills add` or `npx skills update` after upgrading the GitHub release. For local development, symlink: `ln -sfn "$PWD/skills/last30days" ~/.agents/skills/last30days`.

### Dual installs

Marketplace + `npx skills` on the same Claude Code machine → duplicate `/last30days` entries (fixed in v3.3.1 by removing redundant `commands/last30days.md` wrapper; dual skill trees can still coexist).

### OpenClaw and path-discovery loops

Do not implement custom install discovery. Follow `SKILL_DIR` from the `Read` of `SKILL.md`. Update via `clawhub update last30days-official` when behavior drifts.

### Verification smoke test

After updating Claude Code cache:

```text
/last30days birthday gift for 40 year old
```

A healthy install asks a clarifying question before running the engine. If it runs immediately with thin or improvised output, repeat plugin update and cache verification.

## Manifest and repo anchors

| File | Purpose |
| --- | --- |
| `.claude-plugin/marketplace.json` | Claude Code marketplace listing (`plugins[0].version`) |
| `.claude-plugin/plugin.json` | Plugin identity for cache installs |
| `.agents/plugins/marketplace.json` | Agents-style marketplace metadata (local `source`) |
| `gemini-extension.json` | Optional Gemini extension env schema |
| `skills/last30days/agents/openai.yaml` | Codex/OpenAI-agent interface display metadata |
| `skills/last30days/SKILL.md` | Runtime authority (STEP 0, `SKILL_DIR`, invocation contract) |

`tests/test_plugin_contract.py` enforces version alignment across manifests and asserts `.codex-plugin/` stays removed.

## Beta and experimental installs

Experimental work ships from `mvanhorn/last30days-skill-private` as `/last30days-beta` (parallel slash command). Do not mix beta-only behavior into the public marketplace without a review PR to the public repo.

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Marketplace add, `npx skills` global vs project scope, Hermes, symlinks, and version sync expectations.
</Card>
<Card title="Skill contract" href="/skill-contract">
STEP 0 stale-clone guard, pre-flight protocol, engine invocation rules, and `SKILL_DIR` substitution.
</Card>
<Card title="Skill, engine, and harness" href="/skill-engine-harness">
Boundaries between the Agent Skills package, Python engine, and multi-harness runtimes.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
`--diagnose`, missing sources, stale marketplace clones, and thin results.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
Env vars, reasoning provider priority when running headless, and web-backend order.
</Card>
<Card title="Beta channel" href="/beta-channel">
Parallel `/last30days-beta` install and promotion workflow.
</Card>
</CardGroup>