# Skill, engine, and harness

> Project-specific boundaries between the Agent Skills package, Python engine, and multi-harness runtimes that load the skill.

- 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

- `CONCEPTS.md`
- `skills/last30days/SKILL.md`
- `skills/last30days/scripts/last30days.py`
- `AGENTS.md`
- `skills/last30days/scripts/lib/skill_meta.py`

---

---
title: "Skill, engine, and harness"
description: "Project-specific boundaries between the Agent Skills package, Python engine, and multi-harness runtimes that load the skill."
---

`mvanhorn/last30days-skill` ships as an [Agent Skills](https://agentskills.io) package under `skills/last30days/`: `SKILL.md` is the runtime contract the hosting model follows, and `scripts/last30days.py` plus `scripts/lib/` perform retrieval, fusion, and rendering. The product surface is harness-invoked research (`/last30days <topic>` on most hosts); direct `python3 …/last30days.py` is a dev, cron, and scripting fallback only.

## Three layers

| Layer | Location | Owns | Does not own |
|-------|----------|------|----------------|
| **Skill** | `skills/last30days/SKILL.md` + sibling `scripts/`, `references/`, `assets/` | Slash-command UX, pre-flight (Step 0–0.75), query planning on reasoning hosts, synthesis LAWs, which engine flags to pass | Platform HTTP clients, clustering, dedupe, rerank |
| **Engine** | `scripts/last30days.py`, `scripts/lib/*` | v3 pipeline (`pipeline.run`), `--emit` output shapes, `--diagnose`, SQLite `--store`, headless `--auto-resolve` / internal planner | User-facing prose contract, WebSearch supplements, invitation copy |
| **Harness** | Claude Code, Codex, Cursor, Copilot, Gemini CLI, Hermes, OpenClaw, 50+ Agent Skills hosts | Loads `SKILL.md`, exposes tools (Bash, Read, WebSearch), routes `/last30days` | Research algorithms, source scoring |

<Note>
Project vocabulary is fixed in `CONCEPTS.md`: **Skill** = distribution unit; **Engine** = Python implementation; **Harness** = agent runtime that loads the Skill. “Multi-harness” means a feature must work on every install path the Skill supports—not only Claude Code.
</Note>

```mermaid
flowchart TB
  subgraph harness["Harness (Claude Code, Codex, Cursor, Hermes, …)"]
    SC["/last30days slash command"]
    M["Reasoning model"]
    WS["WebSearch / Read / Bash tools"]
    SC --> M
    M --> WS
  end

  subgraph skill["Skill package skills/last30days/"]
    SM["SKILL.md contract"]
    SM -->|"SKILL_DIR/scripts/last30days.py"| ENG
  end

  subgraph engine["Engine scripts/"]
    ENG["last30days.py"]
    LIB["lib/ pipeline · render · env · …"]
    ENG --> LIB
    LIB --> SRC["Reddit · X · YouTube · …"]
  end

  M -->|"Read SKILL.md"| SM
  WS -->|"Bash invoke"| ENG
  ENG -->|"--emit=compact stdout"| M
  M -->|"synthesis + LAW pass-through"| U["User response"]
```

## Skill package layout

Every install layout keeps **`SKILL.md` and `scripts/` as siblings** under one directory (`SKILL_DIR`). The engine entrypoint is always `${SKILL_DIR}/scripts/last30days.py`.

:::files
skills/last30days/
├── SKILL.md              # Runtime spec (~1400+ lines); harness reads this on invoke
├── scripts/
│   ├── last30days.py     # CLI entry (Python 3.12+)
│   ├── lib/              # pipeline, render, env, per-source modules
│   ├── briefing.py       # Trend-monitoring digests (optional)
│   ├── watchlist.py      # Scheduled runs (optional)
│   └── store.py          # SQLite persistence (optional)
├── references/           # Supplemental skill docs (e.g. HTML brief flow)
└── assets/               # Static assets referenced from SKILL.md
:::

The Skill conforms to the Agent Skills open format (`name`, `version`, `description`, `allowed-tools`, `metadata` in YAML frontmatter). Version strings in output come from `SKILL.md` frontmatter via `lib/skill_meta.py`, with an optional `.claude-plugin/plugin.json` walk in `lib/render.py` for marketplace cache installs.

Distribution paths include:

- **Claude Code marketplace** — plugin cache under `~/.claude/plugins/cache/last30days-skill/…` (versioned) plus a known-stale `~/.claude/plugins/marketplaces/` clone (STEP 0 guard).
- **`npx skills add`** — copies into `~/.agents/skills/last30days/` (frozen until re-run); per-host symlinks when supported.
- **Per-harness dirs** — e.g. `~/.codex/skills/last30days/`, `~/.hermes/skills/research/last30days/`.
- **Repo checkout** — `skills/last30days/` in the working tree for development.

<Warning>
Working-tree edits do **not** propagate to `~/.agents/skills/` automatically. Re-run `npx skills add . -g -y` or symlink the working tree for live dev (`ln -sfn "$PWD/skills/last30days" ~/.agents/skills/last30days`).
</Warning>

## Engine responsibilities

`last30days.py` is the sole supported engine entry. It requires **Python 3.12+**, inserts `SCRIPT_DIR` on `sys.path`, and delegates to `lib.pipeline` for orchestration (planner input, parallel source fan-out, fusion, clustering, dedupe, rerank, depth profiles via `--quick` / default / `--deep`).

| Concern | Engine module / surface |
|---------|-------------------------|
| Config & keys | `lib/env.py`, `.env` / keychain patterns |
| Retrieval | `lib/reddit.py`, `lib/bird_x.py`, `lib/youtube_yt.py`, … |
| Output wire format | `lib/render.py` (`--emit=compact|md|json|context|html`) |
| Badge line | `render._render_badge()` — first line of compact/md stdout |
| Class-1 refusal | `lib/preflight.py` before pipeline |
| Headless planning | `lib/planner.py` + `--auto-resolve` when no host WebSearch |
| Version string | `lib/skill_meta.read_skill_version` + `render._skill_version()` |

`lib/__init__.py` is intentionally a bare package marker (no eager imports)—contributor constraint from `AGENTS.md`.

Direct CLI invocation (fallback only):

```bash
python3 skills/last30days/scripts/last30days.py "topic" --emit=compact --diagnose
```

Headless/cron paths may rely on engine `--plan` omission (internal/deterministic planner) or `--auto-resolve` when the harness lacks WebSearch—documented in-engine as the OpenClaw / raw CLI equivalent of SKILL.md Steps 0.55 and 0.75.

## Harness responsibilities

The harness loads `SKILL.md` when the user runs `/last30days <topic>` (or host-specific equivalent). It does **not** forward raw shell syntax from the slash line: pipes, inline flags, and `| pbcopy` on `/last30days …` are invalid; the model maps intent to engine flags, or the operator uses the direct CLI with a real shell.

On reasoning harnesses (Claude Code, Codex with WebSearch, Gemini, Hermes, etc.):

1. **Read** the Skill contract (including STEP 0 stale-clone check for Claude marketplace paths).
2. **Plan** — generate `QUERY_PLAN_JSON` and Step 0.55 targeting; pass `--plan` via a tmpfile (never inline quoted JSON).
3. **Invoke** — Bash `${LAST30DAYS_PYTHON} "${SKILL_DIR}/scripts/last30days.py" … --emit=compact`.
4. **Supplement** — WebSearch steps SKILL.md defines post-engine.
5. **Synthesize** — transform evidence blocks; pass through badge and emoji-tree footer per LAWs.

`SKILL_DIR` is the directory of the **SKILL.md the harness actually loaded**—not a searched precedence list. That keeps spec and code aligned across install layouts without enumerating every host path.

```mermaid
sequenceDiagram
  participant U as User
  participant H as Harness
  participant M as Model
  participant S as SKILL.md
  participant E as last30days.py

  U->>H: /last30days topic
  H->>M: Load skill + tools
  M->>S: Read (STEP 0 if Claude marketplace)
  M->>M: Step 0.55 / 0.75 plan + resolve
  M->>E: Bash SKILL_DIR/scripts/last30days.py --plan … --emit=compact
  E-->>M: Badge + evidence + footer stdout
  M->>M: WebSearch supplements (if available)
  M-->>U: Synthesis + pass-through footer
```

### Platform branch

| Harness capability | Skill path | Engine flags |
|--------------------|------------|--------------|
| WebSearch available | Steps 0.55 + 0.75 mandatory; model is planner (LAW 7) | `--plan "$QUERY_PLAN_FILE"`, targeting flags, `--emit=compact` |
| No WebSearch (OpenClaw, some Codex) | Skip 0.55/0.75 | `--auto-resolve` |
| Agent mode (`--agent` in args) | Skip intro, AskUserQuestion, invitation | Same engine run; structured report template |

Resolve once per session:

- `LAST30DAYS_PYTHON` — Python 3.12+ interpreter for all engine calls.
- `LAST30DAYS_MEMORY_DIR` — raw save root (default `~/Documents/Last30Days`); passed as `--save-dir`.

## Skill ↔ engine contract

The contract is bidirectional: **SKILL.md → flags**, **engine → output shape**.

### SKILL.md → engine

The model must translate user intent into explicit flags the engine understands, including:

| Flag family | Purpose |
|-------------|---------|
| `--plan` | External JSON query plan (reasoning-model path) |
| `--x-handle`, `--subreddits`, `--github-user`, `--github-repo`, TikTok/IG flags | Step 0.55 targeting |
| `--competitors`, `--competitors-plan` | Comparison / vs-mode fan-out |
| `--emit` | Wire format (`compact` is the primary user-facing mode) |
| `--save-dir`, `--save-suffix` | Artifact paths |
| `--quick` / `--deep` | Depth profiles |
| `--diagnose` | Source availability probe (verification) |

<Info>
A new engine flag without a matching `SKILL.md` section is considered **incomplete**: the invoking model will not know the flag exists. Feature design starts from slash-command UX, per `AGENTS.md`.
</Info>

### Engine → model

Default `--emit=compact` stdout includes:

- **Badge** — `🌐 last30days v{version} · synced {date}` (engine-emitted since v3.0.8).
- **Evidence for synthesis** — `<!-- EVIDENCE FOR SYNTHESIS -->` bounded blocks (read, do not emit verbatim — LAW 6).
- **Pass-through footer** — `<!-- PASS-THROUGH FOOTER -->` emoji-tree ending in raw save path (LAW 5).

The model adds narrative (`What I learned:`, KEY PATTERNS, comparison template sections) and must not improvise alternate titles, `Sources:` blocks, or bare `python3 scripts/last30days.py "$TOPIC"` on named entities without `--plan`.

## Install surfaces vs runtime

| Install mechanism | Typical `SKILL_DIR` | Sync model |
|-------------------|---------------------|------------|
| Claude marketplace | `~/.claude/plugins/cache/…/skills/last30days` | Marketplace/plugin update; watch STEP 0 |
| `npx skills add -g` | `~/.agents/skills/last30days` | Re-run add or dev symlink |
| Codex / Cursor skills dir | `~/.codex/skills/last30days` | Host-specific refresh |
| Hermes | `~/.hermes/skills/research/last30days` | `hermes skills install … --force` or symlink |
| Repo dev | `$REPO/skills/last30days` | Immediate on save |

Beta channel (`/last30days-beta` from private repo) is a **parallel Skill install**, not a different engine—see beta docs for promotion boundaries.

## Contributor boundaries

When extending the project:

1. **User-facing behavior** — update `SKILL.md` first (steps, flags, LAWs, examples).
2. **Implementation** — `scripts/last30days.py` + `scripts/lib/`.
3. **Operator knobs** — mirror env vars and CLI flags in `CONFIGURATION.md`.
4. **Tests** — `uv run pytest` (~89 files); version consistency via `tests/test_plugin_contract.py` and `skill_meta.read_skill_version`.

Do not treat the repo as a standalone CLI product in docs or UX: README and PR examples lead with `/last30days <topic>`; direct Python invocation is labeled fallback only.

## Related pages

<CardGroup>
  <Card title="Overview" href="/overview">
    Slash-command vs engine paths, zero-config sources, shortest successful research path.
  </Card>
  <Card title="Skill contract" href="/skill-contract">
    STEP 0 stale-clone guard, pre-flight protocol, SKILL_DIR substitution, invocation rules.
  </Card>
  <Card title="Research pipeline" href="/research-pipeline">
    v3 orchestration inside the engine: planner, fan-out, fusion, clustering, dedupe, rerank.
  </Card>
  <Card title="Output contract" href="/output-contract">
    Badge, LAWs voice rules, --emit modes, evidence blocks, footer pass-through.
  </Card>
  <Card title="Installation" href="/installation">
    Marketplace, npx skills add, Hermes, live-edit symlinks, version sync.
  </Card>
  <Card title="Model clients" href="/model-clients">
    Per-harness install patterns and stale-install avoidance.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Direct last30days.py flags and constraints vs slash-command usage.
  </Card>
</CardGroup>