From a78ab69ffead2c250d7c60eef48052d5b9eff051 Mon Sep 17 00:00:00 2001 From: Julius Smith <2200853+josmithiii@users.noreply.github.com> Date: Mon, 18 May 2026 07:45:27 -0700 Subject: [PATCH] docs(agents): correct install-propagation claim and fill in build/test gaps AGENTS.md said "edits in the working tree propagate live to every harness" after `npx skills add . -g -y`, but the install actually drops a real (frozen-at-install-time) copy at ~/.agents/skills// and per-host symlinks point at *that copy*, not at the working tree. Clarify the mechanism and offer two ways forward: re-run `npx skills add` to sync, or replace the install copy with a working-tree symlink for live-edit. Also fill in two gaps a fresh agent hits on entry: - `uv run pytest` commands for the ~89-file test suite (no test runner was documented before) - Python 3.12+ / `uv` / `.venv/` convention - Brief doc map: CONFIGURATION.md, SKILL.md vs SKILL-original.md, CHANGELOG.md / release-notes.md, HERMES_SETUP.md --- AGENTS.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6d2a74e..7e05d9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,10 @@ Agent Skills package for researching any topic across Reddit, X, YouTube, and we - `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 +- `SKILL.md` (under `skills/last30days/`) — canonical runtime spec the model reads when the slash command fires; `SKILL-original.md` at repo root is the historical v1 spec, kept for reference only +- `CHANGELOG.md` / `release-notes.md` — release history and human-readable notes (CHANGELOG = structured, release-notes = launch copy) +- `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 ` 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. @@ -22,9 +26,18 @@ Agent Skills package for researching any topic across Reddit, X, YouTube, and we 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 +# 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` 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. +- One-time setup: `npx skills add . -g -y` copies the skill into `~/.agents/skills//` (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//` 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