From 5bfb78dc511af005e9544077e1421597c6d7bc4a Mon Sep 17 00:00:00 2001 From: "Thoth Bot (GD)" Date: Tue, 24 Feb 2026 14:37:20 -0800 Subject: [PATCH 1/2] feat(skill): enhance agent skill with when-to-save, annotation conventions, and pipeline integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add 'When to save' section with clear rules for agents - Add setup section with wrapper path and DB config - Add annotation conventions: actor names, confidence guidelines, highlight vs lowlight - Add content pipeline integration workflow (save → ingest → annotate → link to content-board) - Clarify that linkledger wrapper works from any directory --- skills/linkledger-cli-agent/SKILL.md | 47 ++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/skills/linkledger-cli-agent/SKILL.md b/skills/linkledger-cli-agent/SKILL.md index 0307c4c..d3ba345 100644 --- a/skills/linkledger-cli-agent/SKILL.md +++ b/skills/linkledger-cli-agent/SKILL.md @@ -10,12 +10,44 @@ description: Use this skill when an agent needs to store sources in linkledger-c - You need to run ingestion and check item/job status. - You need ranked retrieval (`find`, `brief`) for drafting or research tasks. - You need source-specific ingestion for `article`, `x`, `youtube`, `pdf`, `bluesky`, or `linkedin`. +- You are researching sources for a content packet, blog draft, or any writing task. +- A human sends you a link to remember. + +## Setup +- Binary: `linkledger` (wrapper at `/opt/homebrew/bin/linkledger`) +- DB path is pre-configured via the wrapper (`~/.linkledger/linkledger.db`). No env var needed. +- The wrapper `cd`s into the repo directory automatically — call `linkledger` from anywhere. ## Rules - Prefer `--json` on all commands for deterministic machine parsing. -- For agent annotations (`--actor agent:`), always pass `--confidence 0.0-1.0`. +- For agent annotations, use `--actor agent:` (e.g., `agent:thoth`, `agent:research-scout`). +- Always pass `--confidence 0.0-1.0` with agent annotations. - Keep queries short and specific; broaden only if result count is low. +## When to save +- **Every source you cite** in a draft, outline, or content packet — save it. +- **Every link a human sends you** with context — save it immediately with their note. +- **Newsletter items** you pull for weekly packets — save with `--tags newsletter,`. +- **Don't save** throwaway searches, docs you glanced at but didn't use, or duplicate URLs (dedup is automatic but avoid the noise). + +## Annotation conventions + +### Actor names +Use your agent identity: `agent:thoth`, `agent:research-scout`, etc. Human-provided annotations use `human`. + +### Confidence guidelines +| Confidence | Use when | +|-----------|----------| +| 0.9–1.0 | Direct quote, verified fact, primary source | +| 0.7–0.89 | Strong inference from reliable source | +| 0.5–0.69 | Reasonable interpretation, secondary source | +| < 0.5 | Speculative, opinion-heavy, or unverified | + +### Highlights vs lowlights +- **Highlight**: key claims, quotable insights, data points, novel framings — things you'd cite. +- **Lowlight**: caveats, weaknesses, contradictions, things to be cautious about — things that temper the source. +- **Pin** (`--pin`) a highlight only if it's the single most important takeaway from the source. + ## Core workflow 1. Save source: ```bash @@ -31,8 +63,9 @@ linkledger status --json ``` 4. Add annotations/tags: ```bash -linkledger annotate --highlight "" --actor agent:researcher --confidence 0.82 --json -linkledger tag --add tag1,tag2 --actor agent:researcher --json +linkledger annotate --highlight "" --actor agent:thoth --confidence 0.82 --json +linkledger annotate --lowlight "" --actor agent:thoth --confidence 0.7 --json +linkledger tag --add tag1,tag2 --actor agent:thoth --json ``` 5. Retrieve: ```bash @@ -42,6 +75,14 @@ linkledger brief "" --max-items 10 --json `brief` includes enrichment fields (`summary`, `key_claims`) after worker ingestion succeeds. +## Content pipeline integration +When saving sources for a content packet or blog draft: +1. Save all sources with relevant tags (e.g., `--tags weekly-w09,ai-coding`). +2. Run the worker to ingest. +3. Add highlights for the key claims you plan to reference. +4. Note the `item_id` values — these can be linked to content-board cards for full provenance. +5. When drafting, use `brief ""` to pull compact evidence packs instead of re-reading full articles. + ## Recovery workflow - If `status.item.ingest_status` is `failed`: ```bash From 2504a1efc5e4770c37ddc2b1d990a9cd11697777 Mon Sep 17 00:00:00 2001 From: "Thoth Bot (GD)" Date: Tue, 24 Feb 2026 15:05:30 -0800 Subject: [PATCH 2/2] fix(skill): make setup guidance portable per review feedback - Remove hardcoded /opt/homebrew path assumption - Document both wrapper and repo-local invocation modes - Clarify LINKLEDGER_DB_PATH behavior and cwd default --- skills/linkledger-cli-agent/SKILL.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/skills/linkledger-cli-agent/SKILL.md b/skills/linkledger-cli-agent/SKILL.md index d3ba345..2801e7a 100644 --- a/skills/linkledger-cli-agent/SKILL.md +++ b/skills/linkledger-cli-agent/SKILL.md @@ -14,9 +14,14 @@ description: Use this skill when an agent needs to store sources in linkledger-c - A human sends you a link to remember. ## Setup -- Binary: `linkledger` (wrapper at `/opt/homebrew/bin/linkledger`) -- DB path is pre-configured via the wrapper (`~/.linkledger/linkledger.db`). No env var needed. -- The wrapper `cd`s into the repo directory automatically — call `linkledger` from anywhere. +- **If a wrapper script is installed** (e.g., `/opt/homebrew/bin/linkledger`), it handles `cd` into the repo and sets `LINKLEDGER_DB_PATH` automatically — call `linkledger` from anywhere. +- **Otherwise**, run from the repo directory and set `LINKLEDGER_DB_PATH` explicitly: + ```bash + export LINKLEDGER_DB_PATH="$HOME/.linkledger/linkledger.db" + cd /path/to/linkledger-cli + node dist/cli/index.js + ``` +- The DB defaults to `.linkledger/linkledger.db` relative to cwd if `LINKLEDGER_DB_PATH` is not set. Set it explicitly to avoid writing to unintended locations. ## Rules - Prefer `--json` on all commands for deterministic machine parsing.