From e0f6ef845afeb48fd09581fc9fee83c4439dc36b Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sat, 16 May 2026 17:01:04 -0700 Subject: [PATCH 1/3] docs(claude.md): add Orientation section, reframe as multi-harness Agent Skills package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the spirit of #335 (closed in favor of this fresh PR after the sync.sh thread became obsolete via PR #405). Two changes: 1. Top-of-file description reframed from "Claude Code skill" to "Agent Skills package... installable across Claude Code (most common host), Codex, Cursor, GitHub Copilot, Gemini CLI, and 50+ other Agent Skills hosts". The skill works across every major agent host after the install-modernization work in PR #400/#404/#405/#409. Calling it "Claude Code skill" undersells the surface and biases contributors toward Claude-Code-specific assumptions. 2. New ## Orientation section (4 bullets) framing the project for contributors who would otherwise read the python3 invocation in ## Commands and form a CLI-first mental model. Names the trap explicitly with one concrete invalid-syntax example (`/last30days OpenClaw --emit=html | pbcopy` — slash commands don't pass shell mechanics through). Bullets adapted from #335 with multi-harness framing replacing the Claude-Code-only framing. No code changes. No SKILL.md changes. CLAUDE.md only. AGENTS.md inherits via @CLAUDE.md. --- CLAUDE.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a48197a..b1b1015 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,6 @@ # last30days Skill -Claude Code skill for researching any topic across Reddit, X, YouTube, and web. -Python scripts with multi-source search aggregation. +Agent Skills package for researching any topic across Reddit, X, YouTube, and web. Installable across Claude Code (most common host), Codex, Cursor, GitHub Copilot, Gemini CLI, and 50+ other [Agent Skills](https://agentskills.io) hosts. Python scripts with multi-source search aggregation. ## Structure - `skills/last30days/SKILL.md` — canonical skill definition @@ -9,6 +8,12 @@ Python scripts with multi-source search aggregation. - `skills/last30days/scripts/lib/` — search, enrichment, rendering modules - `skills/last30days/scripts/lib/vendor/bird-search/` — vendored X search client +## Orientation +- This is an Agent Skills package, not a CLI tool. The product is the slash-command-invoked skill (`/last30days ` in most harnesses); `scripts/last30days.py` is implementation. Claude Code is the most common host but not the only one — features must work across every harness the skill installs into. +- Feature design starts from the slash-command UX. A new engine flag with no SKILL.md integration is incomplete — the model invoking the skill won't know the flag exists. +- README and PR examples show `/last30days ` first. Direct CLI invocation (`python3 scripts/last30days.py ...`) is a fallback for scripting, cron, and dev-time engine testing; label it as such, never as the primary path. +- Slash commands don't pass shell mechanics through. `/last30days OpenClaw --emit=html | pbcopy` is invalid in any harness — either use the slash form (no flags or pipes; let the model translate user intent into engine flags) or use the direct CLI form (full `python3 ...` with explicit flags and a real shell). + ## Commands ```bash python3 skills/last30days/scripts/last30days.py "test query" --emit=compact From 1fd763e09f59e4997652ccfb072594131533aee9 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sat, 16 May 2026 17:03:11 -0700 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20flip=20CLAUDE.md=20=E2=86=94=20AGEN?= =?UTF-8?q?TS.md=20=E2=80=94=20AGENTS.md=20becomes=20canonical,=20CLAUDE.m?= =?UTF-8?q?d=20points=20at=20it?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors the multi-harness reframing of the project itself. CLAUDE.md is Claude-Code-specific by name; AGENTS.md is the multi-harness convention that Codex, Cursor, Gemini CLI, GitHub Copilot, and most other Agent Skills hosts also read. The canonical content belongs in the file multi-harness tooling expects. git mv preserves history — the Orientation section and everything else that was in CLAUDE.md is now tracked under AGENTS.md, with full blame continuity. The new CLAUDE.md is a one-line `@AGENTS.md` reference so Claude Code continues to load the content (it follows @ references). --- AGENTS.md | 31 ++++++++++++++++++++++++++++++- CLAUDE.md | 31 +------------------------------ 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a6fce0a..b1b1015 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1,30 @@ -@CLAUDE.md \ No newline at end of file +# last30days Skill + +Agent Skills package for researching any topic across Reddit, X, YouTube, and web. Installable across Claude Code (most common host), Codex, Cursor, GitHub Copilot, Gemini CLI, and 50+ other [Agent Skills](https://agentskills.io) hosts. Python scripts with multi-source search aggregation. + +## Structure +- `skills/last30days/SKILL.md` — canonical skill definition +- `skills/last30days/scripts/last30days.py` — main research engine +- `skills/last30days/scripts/lib/` — search, enrichment, rendering modules +- `skills/last30days/scripts/lib/vendor/bird-search/` — vendored X search client + +## Orientation +- This is an Agent Skills package, not a CLI tool. The product is the slash-command-invoked skill (`/last30days ` in most harnesses); `scripts/last30days.py` is implementation. Claude Code is the most common host but not the only one — features must work across every harness the skill installs into. +- Feature design starts from the slash-command UX. A new engine flag with no SKILL.md integration is incomplete — the model invoking the skill won't know the flag exists. +- README and PR examples show `/last30days ` first. Direct CLI invocation (`python3 scripts/last30days.py ...`) is a fallback for scripting, cron, and dev-time engine testing; label it as such, never as the primary path. +- Slash commands don't pass shell mechanics through. `/last30days OpenClaw --emit=html | pbcopy` is invalid in any harness — either use the slash form (no flags or pipes; let the model translate user intent into engine flags) or use the direct CLI form (full `python3 ...` with explicit flags and a real shell). + +## Commands +```bash +python3 skills/last30days/scripts/last30days.py "test query" --emit=compact +npx skills add . -g -y # one-time: symlink this repo into every detected harness's skill dir +``` + +## Rules +- `lib/__init__.py` must be bare package marker (comment only, NO eager imports) +- One-time setup: `npx skills add . -g -y` creates symlinks from each detected harness's skill dir to this repo. Edits in the working tree propagate live to every harness — no re-deploy step needed. +- Git remote: origin = public (`mvanhorn/last30days-skill`) + +## Beta channel + +Experimental changes get tested on `mvanhorn/last30days-skill-private`, which installs as a parallel `/last30days-beta` slash command. Beta-only changes never ship to public without a review PR here. Workflow guide lives at `BETA.md` in the private repo. Plan that established this setup: `docs/plans/2026-04-17-005-feat-beta-skill-from-private-repo-plan.md`. diff --git a/CLAUDE.md b/CLAUDE.md index b1b1015..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,30 +1 @@ -# last30days Skill - -Agent Skills package for researching any topic across Reddit, X, YouTube, and web. Installable across Claude Code (most common host), Codex, Cursor, GitHub Copilot, Gemini CLI, and 50+ other [Agent Skills](https://agentskills.io) hosts. Python scripts with multi-source search aggregation. - -## Structure -- `skills/last30days/SKILL.md` — canonical skill definition -- `skills/last30days/scripts/last30days.py` — main research engine -- `skills/last30days/scripts/lib/` — search, enrichment, rendering modules -- `skills/last30days/scripts/lib/vendor/bird-search/` — vendored X search client - -## Orientation -- This is an Agent Skills package, not a CLI tool. The product is the slash-command-invoked skill (`/last30days ` in most harnesses); `scripts/last30days.py` is implementation. Claude Code is the most common host but not the only one — features must work across every harness the skill installs into. -- Feature design starts from the slash-command UX. A new engine flag with no SKILL.md integration is incomplete — the model invoking the skill won't know the flag exists. -- README and PR examples show `/last30days ` first. Direct CLI invocation (`python3 scripts/last30days.py ...`) is a fallback for scripting, cron, and dev-time engine testing; label it as such, never as the primary path. -- Slash commands don't pass shell mechanics through. `/last30days OpenClaw --emit=html | pbcopy` is invalid in any harness — either use the slash form (no flags or pipes; let the model translate user intent into engine flags) or use the direct CLI form (full `python3 ...` with explicit flags and a real shell). - -## Commands -```bash -python3 skills/last30days/scripts/last30days.py "test query" --emit=compact -npx skills add . -g -y # one-time: symlink this repo into every detected harness's skill dir -``` - -## Rules -- `lib/__init__.py` must be bare package marker (comment only, NO eager imports) -- One-time setup: `npx skills add . -g -y` creates symlinks from each detected harness's skill dir to this repo. Edits in the working tree propagate live to every harness — no re-deploy step needed. -- Git remote: origin = public (`mvanhorn/last30days-skill`) - -## Beta channel - -Experimental changes get tested on `mvanhorn/last30days-skill-private`, which installs as a parallel `/last30days-beta` slash command. Beta-only changes never ship to public without a review PR here. Workflow guide lives at `BETA.md` in the private repo. Plan that established this setup: `docs/plans/2026-04-17-005-feat-beta-skill-from-private-repo-plan.md`. +@AGENTS.md From 9fe4b8f1308d1fd2fe1df7974f302198e47801ba Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sat, 16 May 2026 18:42:14 -0700 Subject: [PATCH 3/3] Update AGENTS.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b1b1015..6c5d0b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,9 +16,9 @@ Agent Skills package for researching any topic across Reddit, X, YouTube, and we ## Commands ```bash +# Dev/fallback: direct engine invocation (scripting, cron, or engine testing only) python3 skills/last30days/scripts/last30days.py "test query" --emit=compact npx skills add . -g -y # one-time: symlink this repo into every detected harness's skill dir -``` ## Rules - `lib/__init__.py` must be bare package marker (comment only, NO eager imports)