Matt Van Horn
26da1e157c
* chore: remove dev artifacts from installer scan surface Hermes (and other harnesses that clone raw GitHub instead of honoring .clawhubignore) scan files that never reach an installed skill, producing a wall of false-positive security findings. Remove the stale SKILL-original.md backup, internal docs/plans and docs/test-results, and release-notes.md so the scanned tree matches what actually ships. These were already excluded from the ClawHub bundle via .clawhubignore and from git archives via .gitattributes export-ignore. No runtime files change. Refs #464 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: drop dangling SKILL-original.md reference in AGENTS.md Greptile-flagged: the deletion left a 'kept for reference only' pointer to the removed file. Refs #465 --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
67 lines
5.8 KiB
Markdown
67 lines
5.8 KiB
Markdown
# 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 / runtime spec the model reads when the slash command fires
|
|
- `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
|
|
- `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`)
|
|
- `CONCEPTS.md` — shared domain vocabulary (Skill, Engine, Harness, Beta channel) — relevant when orienting to the codebase or discussing project terminology
|
|
- `CONFIGURATION.md` — user-facing knobs (env vars, flags, per-host install patterns); keep in sync per the rules below
|
|
- `CHANGELOG.md` — structured release history (launch copy lives in GitHub Releases)
|
|
- `HERMES_SETUP.md` — install instructions for the Hermes harness specifically
|
|
|
|
## Orientation
|
|
- This is an Agent Skills package, not a CLI tool. The product is the slash-command-invoked skill (`/last30days <topic>` 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 <topic>` 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
|
|
# 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 # copies skill into ~/.agents/skills/<name>/ (frozen at install time); re-run to sync working-tree edits — see Rules below
|
|
|
|
# Tests (pytest, ~89 files under tests/, configured in pyproject.toml)
|
|
uv run pytest # full suite
|
|
uv run pytest tests/test_dedupe_v3.py # single file
|
|
uv run pytest tests/test_dedupe_v3.py -k some_case # single case
|
|
uv run pytest --cov # with coverage (skips lib/vendor/)
|
|
```
|
|
|
|
Python 3.12+ required. Use `uv` for the env; the venv lives at `.venv/`.
|
|
|
|
## Rules
|
|
- `lib/__init__.py` must be bare package marker (comment only, NO eager imports)
|
|
- One-time setup: `npx skills add . -g -y` copies the skill into `~/.agents/skills/<name>/` (real directory) and, for harnesses that support symlinked skill dirs, drops a per-host symlink pointing at that copy. **Working-tree edits do NOT propagate automatically** — the `~/.agents/skills/<name>/` copy is frozen at install time. To sync after edits, re-run `npx skills add . -g -y`. For live-edit on a dev machine, replace the install copy with a symlink to the working tree: `ln -sfn "$PWD/skills/last30days" ~/.agents/skills/last30days` (run from the repo root).
|
|
- Git remote: origin = public (`mvanhorn/last30days-skill`)
|
|
|
|
## Security hygiene
|
|
- Never commit real API keys, browser cookies, auth tokens, app passwords, access tokens, or `.env` contents.
|
|
- Use the env-based auth patterns in `skills/last30days/scripts/lib/env.py`; tests and fixtures must use obvious dummy values only.
|
|
- Keep examples safe by redacting secrets and avoiding copy/pasteable live credentials in docs, fixtures, and test data.
|
|
- Do not weaken or disable the advisory security workflow (`.github/workflows/security.yml`) without explaining why in the PR description or review thread.
|
|
|
|
## Maintaining CONFIGURATION.md
|
|
|
|
`CONFIGURATION.md` is the user-facing configuration reference — save paths, per-source API keys, web-search backend priority, trend-monitoring stack, per-client install patterns. Distinct from `SKILL.md` (the canonical runtime spec).
|
|
|
|
Update `CONFIGURATION.md` when:
|
|
|
|
- adding a new env var (e.g. `LAST30DAYS_*`, `BSKY_*`, `*_API_KEY`)
|
|
- adding a new CLI flag that affects configuration (e.g. `--store`, `--web-backend`)
|
|
- adding a new per-client install pattern (Claude Code, Gemini, Codex, Cursor, Hermes…)
|
|
- adding a new optional source that requires its own credential
|
|
- changing the priority order of config layers (per-run flag > env > `.env` file > defaults)
|
|
|
|
Keep the existing structure organized by how often each layer is touched: per-run flags → env vars / `.env` → optional trend-monitoring stack → per-client patterns. Add new content into the right section rather than appending at the end.
|
|
|
|
When a new config concept lands in `SKILL.md` or `AGENTS.md`, mirror the user-facing knob in `CONFIGURATION.md` so non-agent readers can configure the skill without reverse-engineering it from the runtime spec.
|
|
|
|
## 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`.
|