📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+2
-2
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "antigravity-awesome-skills",
|
||||
"version": "13.12.0",
|
||||
"description": "Plugin-safe Claude Code distribution of Antigravity Awesome Skills with 1,878 supported skills.",
|
||||
"version": "13.13.0",
|
||||
"description": "Plugin-safe Claude Code distribution of Antigravity Awesome Skills with 1,884 supported skills.",
|
||||
"author": {
|
||||
"name": "sickn33 and contributors",
|
||||
"url": "https://github.com/sickn33/antigravity-awesome-skills"
|
||||
|
||||
+170
@@ -0,0 +1,170 @@
|
||||
---
|
||||
name: codex-profiles
|
||||
description: "Use codex-profiles to run Codex CLI or Codex Desktop with isolated CODEX_HOME profiles for separate accounts, projects, and local state."
|
||||
category: productivity
|
||||
risk: critical
|
||||
source: community
|
||||
source_repo: Ducksss/codex-profiles
|
||||
source_type: community
|
||||
date_added: "2026-07-08"
|
||||
author: Ducksss
|
||||
tags: [codex, codex-cli, profiles, code-home, account-isolation, desktop]
|
||||
tools: [codex]
|
||||
license: "MIT"
|
||||
license_source: "https://github.com/Ducksss/codex-profiles/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# Codex Profiles
|
||||
|
||||
## Overview
|
||||
|
||||
Use `codex-profiles` when a user wants separate Codex CLI or Codex Desktop contexts for work, personal, school, client, or project-specific activity. The tool wraps Codex's `CODEX_HOME` support so each profile has its own Codex home directory for auth, config, sessions, connectors, plugins, caches, logs, and local state.
|
||||
|
||||
This skill is for profile selection and operational safety around that boundary. It is not an official OpenAI project, and it does not provide full OS-level isolation.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when the user wants to keep multiple Codex accounts or project contexts separate on one machine.
|
||||
- Use when a workflow needs a different `CODEX_HOME` without manually exporting environment variables.
|
||||
- Use when diagnosing which Codex profile is active or whether profiles are logged in.
|
||||
- Use when the user asks about Codex account switching without copying `auth.json`.
|
||||
- Use when launching Codex Desktop from a profile, only after confirming the user accepts app/process disruption.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Confirm Scope and Installation
|
||||
|
||||
First check whether the user wants CLI-only profile switching or Codex Desktop profile launching. Desktop operations can quit, launch, clone, or rebuild app instances, so get explicit approval before running them.
|
||||
|
||||
If the tool is already installed, inspect the live command surface:
|
||||
|
||||
```bash
|
||||
codex-profile --help
|
||||
codex-profile doctor
|
||||
codex-profile list
|
||||
codex-profile status
|
||||
```
|
||||
|
||||
If it is not installed, prefer package-manager installs the user can inspect and control:
|
||||
|
||||
```bash
|
||||
npm install -g codex-profile
|
||||
brew install Ducksss/tap/codex-profile
|
||||
```
|
||||
|
||||
Do not run remote install scripts automatically. If the user asks for a source install, clone the repository and inspect its install instructions first.
|
||||
|
||||
### Step 2: Create or Select a Profile
|
||||
|
||||
Create a new isolated Codex home only when the user names the intended profile:
|
||||
|
||||
```bash
|
||||
codex-profile init work
|
||||
codex-profile path work
|
||||
```
|
||||
|
||||
Ask the user to log in once per profile when needed:
|
||||
|
||||
```bash
|
||||
codex-profile login work
|
||||
```
|
||||
|
||||
Do not copy, parse, print, or migrate `auth.json` tokens between profiles.
|
||||
|
||||
### Step 3: Run Codex CLI With a Profile
|
||||
|
||||
Use the CLI profile wrapper for ordinary agent work:
|
||||
|
||||
```bash
|
||||
codex-profile cli work
|
||||
codex-profile cli work exec "run tests and summarize failures"
|
||||
```
|
||||
|
||||
For one-off shell sessions, prefer the tool's environment or shell activation commands after checking `--help`:
|
||||
|
||||
```bash
|
||||
codex-profile env work
|
||||
codex-profile shell-init --help
|
||||
```
|
||||
|
||||
### Step 4: Use Desktop Profile Commands Carefully
|
||||
|
||||
Codex Desktop launch flows can affect running app state. Before running them, state which profile, app mode, and workspace will be used, then wait for approval.
|
||||
|
||||
```bash
|
||||
codex-profile app work ~/Dev/project
|
||||
codex-profile app work --instance ~/Dev/project
|
||||
```
|
||||
|
||||
Use `--instance` only when the user wants side-by-side Desktop profiles and accepts the additional local app clone and separate Electron user-data boundary.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Read-Only Profile Audit
|
||||
|
||||
```bash
|
||||
codex-profile list
|
||||
codex-profile status
|
||||
codex-profile doctor
|
||||
```
|
||||
|
||||
Use this before changing profile state. It should not expose token contents.
|
||||
|
||||
### Example 2: CLI Task in a Work Profile
|
||||
|
||||
```bash
|
||||
codex-profile cli work exec "inspect this repository and run its test suite"
|
||||
```
|
||||
|
||||
Confirm the profile name is intentional before running long tasks.
|
||||
|
||||
### Example 3: Manual CODEX_HOME Equivalent
|
||||
|
||||
If the wrapper is unavailable, explain the underlying boundary instead of improvising token movement:
|
||||
|
||||
```bash
|
||||
CODEX_HOME="$HOME/.codex-work" codex
|
||||
CODEX_HOME="$HOME/.codex-work" codex exec "review this change"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep profile names explicit and boring, such as `work`, `personal`, `client-a`, or `school`.
|
||||
- Use `status`, `list`, and `doctor` before destructive or Desktop actions.
|
||||
- Treat each profile as a separate local Codex home, not as a full sandbox.
|
||||
- Keep secrets inside the account/profile that owns them; do not copy auth files between profiles.
|
||||
- Prefer CLI profile commands for routine work and reserve Desktop app commands for user-approved context switches.
|
||||
- Verify behavior against the installed `codex-profile --help`, because command flags can change.
|
||||
|
||||
## Limitations
|
||||
|
||||
- `codex-profiles` is community-maintained and is not an official OpenAI tool.
|
||||
- It isolates Codex state through separate `CODEX_HOME` directories; it does not isolate the operating-system user, shell history, SSH keys, browser cookies, GitHub CLI auth, or unrelated application state.
|
||||
- Desktop profile launch behavior is macOS-focused and can change with Codex Desktop releases.
|
||||
- Existing Codex sessions may still contain project context from before a profile strategy was adopted.
|
||||
- The tool does not replace backups for important Codex state.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- Never copy, print, parse, or migrate `auth.json` tokens as a shortcut.
|
||||
- Do not run Desktop launch, app clone, rebuild, remove, or profile deletion commands without explicit user approval.
|
||||
- Use `codex-profile remove` only after confirming the exact profile path and whether the user needs a backup.
|
||||
- Do not assume profile isolation protects credentials outside `CODEX_HOME`.
|
||||
- Avoid remote install scripts in automated agent runs; prefer inspectable package-manager or source-install steps.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** A user expects profile switching to isolate GitHub CLI, SSH, or browser state.
|
||||
**Solution:** Explain that `codex-profiles` isolates Codex home state only; check and switch other tools separately.
|
||||
|
||||
- **Problem:** A Desktop command disrupts an active session.
|
||||
**Solution:** Ask before Desktop operations and prefer CLI commands when the user only needs isolated command-line work.
|
||||
|
||||
- **Problem:** A profile exists but is logged out or missing connectors.
|
||||
**Solution:** Run `codex-profile status` and have the user log in or configure connectors inside that profile.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@environment-setup-guide` - Use when installing or documenting local development tools.
|
||||
- `@codex-maintenance` - Use when maintaining local Codex Desktop, MCP, plugin, or cache surfaces.
|
||||
- `@filesystem-context` - Use when reasoning about local files, config paths, and workspace boundaries.
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: go-in-depth
|
||||
description: Go in depth harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report.
|
||||
risk: safe
|
||||
source: self
|
||||
source_type: self
|
||||
date_added: "2026-07-07"
|
||||
---
|
||||
|
||||
# Go In Depth
|
||||
|
||||
## Overview
|
||||
|
||||
Go in depth harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report. Run the "go-in-depth" workflow.
|
||||
|
||||
## When to Use
|
||||
|
||||
When the user wants a deep, multi-source, fact-checked research report on any topic. BEFORE invoking, check if the question is specific enough to research directly — if underspecified (e.g., "what car to buy" without budget/use-case/region), ask 2-3 clarifying questions to narrow scope. Then pass the refined question as args, weaving the answers in.
|
||||
|
||||
## How It Works
|
||||
|
||||
Phases:
|
||||
- Scope: Decompose question (from args) into 5 search angles
|
||||
- Search: 5 parallel WebSearch agents, one per angle
|
||||
- Fetch: URL-dedup, fetch top 15 sources, extract falsifiable claims
|
||||
- Verify: 3-vote adversarial verification per claim (need 2/3 refutes to kill)
|
||||
- Synthesize: Merge semantic dupes, rank by confidence, cite sources
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Run go-in-depth workflow
|
||||
```
|
||||
Workflow({ name: "go-in-depth" })
|
||||
```
|
||||
|
||||
### Example 2: Research with refined question
|
||||
```
|
||||
Workflow({ name: "go-in-depth", args: { query: "best hybrid cars under $30k in the US for families" } })
|
||||
```
|
||||
|
||||
### Example 3: Deep dive into a technical concept
|
||||
```
|
||||
Workflow({ name: "go-in-depth", args: { query: "how does the transformer architecture handle positional encoding?" } })
|
||||
```
|
||||
|
||||
### Example 4: Fact-checking a medical claim
|
||||
```
|
||||
Workflow({ name: "go-in-depth", args: { query: "efficacy of intermittent fasting for long-term weight loss in adults" } })
|
||||
```
|
||||
|
||||
## Workflow Script
|
||||
|
||||
[scripts/workflow-script.js](scripts/workflow-script.js)
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Slow execution**: Multi-agent searches, fetching, and 3-vote verification take significant time. Not for quick facts.
|
||||
- **Context intensive**: Analyzing 15 full sources uses large context limits.
|
||||
- **Synthesis risks**: May struggle if source material is weak or equally conflicting.
|
||||
+350
@@ -0,0 +1,350 @@
|
||||
export const meta = {
|
||||
name: 'go-in-depth',
|
||||
description: 'Go in depth harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report.',
|
||||
whenToUse: 'When the user wants a deep, multi-source, fact-checked research report on any topic. BEFORE invoking, check if the question is specific enough to research directly — if underspecified (e.g., "what car to buy" without budget/use-case/region), ask 2-3 clarifying questions to narrow scope. Then pass the refined question as args, weaving the answers in.',
|
||||
phases: [{"title":"Scope","detail":"Decompose question (from args) into 5 search angles"},{"title":"Search","detail":"5 parallel WebSearch agents, one per angle"},{"title":"Fetch","detail":"URL-dedup, fetch top 15 sources, extract falsifiable claims"},{"title":"Verify","detail":"3-vote adversarial verification per claim (need 2/3 refutes to kill)"},{"title":"Synthesize","detail":"Merge semantic dupes, rank by confidence, cite sources"}],
|
||||
}
|
||||
|
||||
// go-in-depth: Scope → pipeline(Search → URL-dedup → Fetch+Extract) → 3-vote Verify → Synthesize
|
||||
// Uses a bug-hunting-style fan-out and verification pattern, adapted for web research.
|
||||
// Question is passed via Workflow({name: 'go-in-depth', args: '<question>'}).
|
||||
|
||||
const VOTES_PER_CLAIM = 3
|
||||
const REFUTATIONS_REQUIRED = 2
|
||||
const MAX_FETCH = 15
|
||||
const MAX_VERIFY_CLAIMS = 25
|
||||
|
||||
// ─── Schemas ───
|
||||
const SCOPE_SCHEMA = {
|
||||
type: "object", required: ["question", "angles", "summary"],
|
||||
properties: {
|
||||
question: { type: "string" },
|
||||
summary: { type: "string" },
|
||||
angles: { type: "array", minItems: 3, maxItems: 6, items: {
|
||||
type: "object", required: ["label", "query"],
|
||||
properties: {
|
||||
label: { type: "string" },
|
||||
query: { type: "string" },
|
||||
rationale: { type: "string" },
|
||||
},
|
||||
}},
|
||||
},
|
||||
}
|
||||
const SEARCH_SCHEMA = {
|
||||
type: "object", required: ["results"],
|
||||
properties: {
|
||||
results: { type: "array", maxItems: 6, items: {
|
||||
type: "object", required: ["url", "title", "relevance"],
|
||||
properties: {
|
||||
url: { type: "string" },
|
||||
title: { type: "string" },
|
||||
snippet: { type: "string" },
|
||||
relevance: { enum: ["high", "medium", "low"] },
|
||||
},
|
||||
}},
|
||||
},
|
||||
}
|
||||
const EXTRACT_SCHEMA = {
|
||||
type: "object", required: ["claims", "sourceQuality"],
|
||||
properties: {
|
||||
sourceQuality: { enum: ["primary", "secondary", "blog", "forum", "unreliable"] },
|
||||
publishDate: { type: "string" },
|
||||
claims: { type: "array", maxItems: 5, items: {
|
||||
type: "object", required: ["claim", "quote", "importance"],
|
||||
properties: {
|
||||
claim: { type: "string" },
|
||||
quote: { type: "string" },
|
||||
importance: { enum: ["central", "supporting", "tangential"] },
|
||||
},
|
||||
}},
|
||||
},
|
||||
}
|
||||
const VERDICT_SCHEMA = {
|
||||
type: "object", required: ["refuted", "evidence", "confidence"],
|
||||
properties: {
|
||||
refuted: { type: "boolean" },
|
||||
evidence: { type: "string" },
|
||||
confidence: { enum: ["high", "medium", "low"] },
|
||||
counterSource: { type: "string" },
|
||||
},
|
||||
}
|
||||
const REPORT_SCHEMA = {
|
||||
type: "object", required: ["summary", "findings", "caveats"],
|
||||
properties: {
|
||||
summary: { type: "string" },
|
||||
findings: { type: "array", items: {
|
||||
type: "object", required: ["claim", "confidence", "sources", "evidence"],
|
||||
properties: {
|
||||
claim: { type: "string" },
|
||||
confidence: { enum: ["high", "medium", "low"] },
|
||||
sources: { type: "array", items: { type: "string" } },
|
||||
evidence: { type: "string" },
|
||||
vote: { type: "string" },
|
||||
},
|
||||
}},
|
||||
caveats: { type: "string" },
|
||||
openQuestions: { type: "array", items: { type: "string" } },
|
||||
},
|
||||
}
|
||||
|
||||
// ─── Phase 0: Scope — decompose question into search angles ───
|
||||
phase("Scope")
|
||||
const QUESTION = (typeof args === "string" ? args.trim() : args?.query?.trim()) || ""
|
||||
if (!QUESTION) {
|
||||
return { error: "No research question provided. Pass it as args: Workflow({name: 'go-in-depth', args: '<question>'})." }
|
||||
}
|
||||
const scope = await agent(
|
||||
"Decompose this research question into complementary search angles.\n\n" +
|
||||
"## Question\n" + QUESTION + "\n\n" +
|
||||
"## Task\n" +
|
||||
"Generate 5 distinct web search queries that together cover the question from different angles. Pick angles that suit the question's domain. Examples:\n" +
|
||||
"- broad/primary · academic/technical · recent news · contrarian/skeptical · practitioner/implementation\n" +
|
||||
"- For medical: anatomy · common causes · serious differentials · authoritative refs · red flags\n" +
|
||||
"- For tech: state-of-art · benchmarks · limitations · industry adoption · cost/tradeoffs\n\n" +
|
||||
"Make queries specific enough to surface high-signal results. Avoid redundancy.\n" +
|
||||
"Return: the question (verbatim or lightly normalized), a 1-2 sentence decomposition strategy, and the angles.\n\nStructured output only.",
|
||||
{ label: "scope", schema: SCOPE_SCHEMA }
|
||||
)
|
||||
if (!scope) {
|
||||
return { error: "Scope agent returned no result — cannot decompose the research question." }
|
||||
}
|
||||
log("Q: " + QUESTION.slice(0, 80) + (QUESTION.length > 80 ? "…" : ""))
|
||||
log("Decomposed into " + scope.angles.length + " angles: " + scope.angles.map(a => a.label).join(", "))
|
||||
|
||||
// ─── Dedup state — accumulates across searchers as they complete ───
|
||||
const normURL = u => {
|
||||
try {
|
||||
const p = new URL(u)
|
||||
return (p.hostname.replace(/^www\./, "") + p.pathname.replace(/\/$/, "")).toLowerCase()
|
||||
} catch { return u.toLowerCase() }
|
||||
}
|
||||
const seen = new Map()
|
||||
const dupes = []
|
||||
const budgetDropped = []
|
||||
const relRank = { high: 0, medium: 1, low: 2 }
|
||||
let fetchSlots = MAX_FETCH
|
||||
|
||||
// ─── Prompts ───
|
||||
const SEARCH_PROMPT = (angle) =>
|
||||
"## Web Searcher: " + angle.label + "\n\n" +
|
||||
"Research question: \"" + QUESTION + "\"\n\n" +
|
||||
"Your angle: **" + angle.label + "** — " + (angle.rationale || "") + "\n" +
|
||||
"Search query: `" + angle.query + "`\n\n" +
|
||||
"## Task\nUse WebSearch with the query above (or a refined version). Return the top 4-6 most relevant results.\n" +
|
||||
"Rank by relevance to the ORIGINAL question, not just the search query. Skip obvious SEO spam/content farms.\n" +
|
||||
"Include a short snippet capturing why each result is relevant.\n\nStructured output only."
|
||||
|
||||
const FETCH_PROMPT = (source, angle) =>
|
||||
"## Source Extractor\n\n" +
|
||||
"Research question: \"" + QUESTION + "\"\n\n" +
|
||||
"Fetch and extract key claims from this source:\n" +
|
||||
"**URL:** " + source.url + "\n**Title:** " + source.title + "\n**Found via:** " + angle + " search\n\n" +
|
||||
"## Task\n1. Use WebFetch to retrieve the page content.\n" +
|
||||
"2. Assess source quality: primary research/institution? secondary reporting? blog/opinion? forum? unreliable?\n" +
|
||||
"3. Extract 2-5 FALSIFIABLE claims that bear on the research question. Each claim must:\n" +
|
||||
" - be a concrete, checkable statement (not vague generalities)\n" +
|
||||
" - include a direct quote from the source as support\n" +
|
||||
" - be rated central/supporting/tangential to the research question\n" +
|
||||
"4. Note publish date if available.\n\n" +
|
||||
"If the fetch fails or the page is irrelevant/paywalled, return claims: [] and sourceQuality: \"unreliable\".\n\nStructured output only."
|
||||
|
||||
const VERIFY_PROMPT = (claim, v) =>
|
||||
"## Adversarial Claim Verifier (voter " + (v + 1) + "/" + VOTES_PER_CLAIM + ")\n\n" +
|
||||
"Be SKEPTICAL. Try to REFUTE this claim. ≥" + REFUTATIONS_REQUIRED + "/" + VOTES_PER_CLAIM + " refutations kill it.\n\n" +
|
||||
"## Research question\n" + QUESTION + "\n\n" +
|
||||
"## Claim under review\n\"" + claim.claim + "\"\n\n" +
|
||||
"**Source:** " + claim.sourceUrl + " (" + claim.sourceQuality + ")\n" +
|
||||
"**Supporting quote:** \"" + claim.quote + "\"\n\n" +
|
||||
"## Checklist\n" +
|
||||
"1. Is the claim actually supported by the quote, or is it an overreach/misread?\n" +
|
||||
"2. WebSearch for contradicting evidence — does any credible source dispute or heavily qualify this?\n" +
|
||||
"3. Is the source quality sufficient for the claim's strength? (extraordinary claims need primary sources)\n" +
|
||||
"4. Is the claim outdated? (check dates — old claims about fast-moving fields are suspect)\n" +
|
||||
"5. Is this a marketing claim / press release / cherry-picked benchmark / forum speculation?\n\n" +
|
||||
"**refuted=true** if: unsupported by quote / contradicted / low-quality source for strong claim / outdated / marketing fluff.\n" +
|
||||
"**refuted=false** ONLY if: claim is well-supported, current, and source quality matches claim strength.\n" +
|
||||
"Default to refuted=true if uncertain.\n\nStructured output only. Evidence MUST be specific."
|
||||
|
||||
// ─── Pipeline: search → dedup → fetch+extract (no barrier) ───
|
||||
const searchResults = await pipeline(
|
||||
scope.angles,
|
||||
|
||||
angle => agent(SEARCH_PROMPT(angle), {
|
||||
label: "search:" + angle.label, phase: "Search", schema: SEARCH_SCHEMA
|
||||
}).then(r => {
|
||||
if (!r) return null
|
||||
log(angle.label + ": " + r.results.length + " results")
|
||||
return { angle: angle.label, results: r.results }
|
||||
}),
|
||||
|
||||
searchResult => {
|
||||
const sorted = [...searchResult.results].sort((a, b) => relRank[a.relevance] - relRank[b.relevance])
|
||||
const novel = sorted.filter(r => {
|
||||
const key = normURL(r.url)
|
||||
if (seen.has(key)) {
|
||||
dupes.push({ ...r, angle: searchResult.angle, dupOf: seen.get(key) })
|
||||
return false
|
||||
}
|
||||
if (fetchSlots <= 0) {
|
||||
budgetDropped.push({ ...r, angle: searchResult.angle })
|
||||
return false
|
||||
}
|
||||
seen.set(key, { angle: searchResult.angle, title: r.title })
|
||||
fetchSlots--
|
||||
return true
|
||||
})
|
||||
if (novel.length < searchResult.results.length) {
|
||||
log(searchResult.angle + ": " + novel.length + " novel (" + (searchResult.results.length - novel.length) + " filtered)")
|
||||
}
|
||||
return parallel(
|
||||
novel.map(source => () => {
|
||||
let host = "unknown"
|
||||
try { host = new URL(source.url).hostname.replace(/^www\./, "") } catch {}
|
||||
return agent(FETCH_PROMPT(source, searchResult.angle), {
|
||||
label: "fetch:" + host,
|
||||
phase: "Fetch",
|
||||
schema: EXTRACT_SCHEMA,
|
||||
}).then(ext => {
|
||||
// User-skip → null; drop it (filtered by searchResults.flat().filter(Boolean))
|
||||
// rather than throwing into .catch() and mislabeling it "unreliable".
|
||||
if (!ext) return null
|
||||
return {
|
||||
url: source.url, title: source.title, angle: searchResult.angle,
|
||||
sourceQuality: ext.sourceQuality, publishDate: ext.publishDate,
|
||||
claims: ext.claims.map(c => ({ ...c, sourceUrl: source.url, sourceQuality: ext.sourceQuality })),
|
||||
}
|
||||
}).catch(e => {
|
||||
log("fetch failed: " + source.url + " — " + (e.message || e))
|
||||
return { url: source.url, title: source.title, angle: searchResult.angle, sourceQuality: "unreliable", claims: [] }
|
||||
})
|
||||
})
|
||||
)
|
||||
}
|
||||
)
|
||||
|
||||
const allSources = searchResults.flat().filter(Boolean)
|
||||
const allClaims = allSources.flatMap(s => s.claims)
|
||||
const impRank = { central: 0, supporting: 1, tangential: 2 }
|
||||
const qualRank = { primary: 0, secondary: 1, blog: 2, forum: 3, unreliable: 4 }
|
||||
|
||||
const rankedClaims = [...allClaims]
|
||||
.sort((a, b) => (impRank[a.importance] - impRank[b.importance]) || (qualRank[a.sourceQuality] - qualRank[b.sourceQuality]))
|
||||
.slice(0, MAX_VERIFY_CLAIMS)
|
||||
|
||||
log("Fetched " + allSources.length + " sources → " + allClaims.length + " claims → verifying top " + rankedClaims.length)
|
||||
|
||||
if (rankedClaims.length === 0) {
|
||||
return {
|
||||
question: QUESTION,
|
||||
summary: "No claims extracted. " + allSources.length + " sources fetched, all empty/failed. " + dupes.length + " URL dupes, " + budgetDropped.length + " budget-dropped.",
|
||||
findings: [], refuted: [], sources: allSources.map(s => ({ url: s.url, quality: s.sourceQuality })),
|
||||
stats: { angles: scope.angles.length, sources: allSources.length, claims: 0, dupes: dupes.length },
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Verify: 3-vote adversarial ───
|
||||
// Barrier here is intentional — claim pool must be fully assembled before ranking/verification.
|
||||
phase("Verify")
|
||||
const voted = (await parallel(
|
||||
rankedClaims.map(claim => () =>
|
||||
parallel(
|
||||
Array.from({ length: VOTES_PER_CLAIM }, (_, v) => () =>
|
||||
agent(VERIFY_PROMPT(claim, v), {
|
||||
label: "v" + v + ":" + claim.claim.slice(0, 40),
|
||||
phase: "Verify",
|
||||
schema: VERDICT_SCHEMA,
|
||||
})
|
||||
)
|
||||
).then(verdicts => {
|
||||
// A vote can be null (user-skip or agent error) — treat as abstain.
|
||||
const valid = verdicts.filter(Boolean)
|
||||
const refuted = valid.filter(v => v.refuted).length
|
||||
// Survive only if the claim was actually adjudicated: a quorum of
|
||||
// valid votes AND fewer than REFUTATIONS_REQUIRED refuting. Too many
|
||||
// abstentions = unverified, which must NOT pass into the report
|
||||
// (otherwise all-abstain → refuted=0 → false survive).
|
||||
const abstained = VOTES_PER_CLAIM - valid.length
|
||||
const survives = valid.length >= REFUTATIONS_REQUIRED && refuted < REFUTATIONS_REQUIRED
|
||||
log("\"" + claim.claim.slice(0, 50) + "…\": " + (valid.length - refuted) + "-" + refuted + (abstained > 0 ? " (" + abstained + " abstain)" : "") + " " + (survives ? "✓" : "✗"))
|
||||
return { ...claim, verdicts: valid, refutedVotes: refuted, survives }
|
||||
})
|
||||
)
|
||||
)).filter(Boolean)
|
||||
|
||||
const confirmed = voted.filter(c => c.survives)
|
||||
const killed = voted.filter(c => !c.survives)
|
||||
log("Verify done: " + voted.length + " claims → " + confirmed.length + " confirmed, " + killed.length + " killed")
|
||||
|
||||
if (confirmed.length === 0) {
|
||||
return {
|
||||
question: QUESTION,
|
||||
summary: "All " + voted.length + " claims refuted by adversarial verification. Research inconclusive — sources may be low-quality or claims overstated.",
|
||||
findings: [],
|
||||
refuted: killed.map(c => ({ claim: c.claim, vote: (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes, source: c.sourceUrl })),
|
||||
sources: allSources.map(s => ({ url: s.url, quality: s.sourceQuality, claimCount: s.claims.length })),
|
||||
stats: { angles: scope.angles.length, sources: allSources.length, claims: allClaims.length, verified: voted.length, confirmed: 0, killed: killed.length },
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Synthesize ───
|
||||
phase("Synthesize")
|
||||
const confRank = { high: 0, medium: 1, low: 2 }
|
||||
const block = confirmed.map((c, i) => {
|
||||
const best = c.verdicts.filter(v => !v.refuted).sort((a, b) => confRank[a.confidence] - confRank[b.confidence])[0]
|
||||
return "### [" + i + "] " + c.claim + "\n" +
|
||||
"Vote: " + (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes + " · Source: " + c.sourceUrl + " (" + c.sourceQuality + ")\n" +
|
||||
"Quote: \"" + c.quote + "\"\nVerifier evidence (" + best.confidence + "): " + best.evidence + "\n"
|
||||
}).join("\n")
|
||||
|
||||
const killedBlock = killed.length > 0
|
||||
? "\n## Refuted claims (for transparency)\n" +
|
||||
killed.map(c => "- \"" + c.claim + "\" (" + c.sourceUrl + ", vote " + (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes + ")").join("\n")
|
||||
: ""
|
||||
|
||||
const report = await agent(
|
||||
"## Synthesis: research report\n\n" +
|
||||
"**Question:** " + QUESTION + "\n\n" +
|
||||
confirmed.length + " claims survived " + VOTES_PER_CLAIM + "-vote adversarial verification. Merge semantic duplicates and synthesize.\n\n" +
|
||||
"## Confirmed claims\n" + block + "\n" + killedBlock + "\n\n" +
|
||||
"## Instructions\n" +
|
||||
"1. Identify claims that say the same thing — merge them, combine their sources.\n" +
|
||||
"2. Group related claims into coherent findings. Each finding should directly address the research question.\n" +
|
||||
"3. Assign confidence per finding: high (multiple primary sources, unanimous votes), medium (secondary sources or split votes), low (single source or blog-quality).\n" +
|
||||
"4. Write a 3-5 sentence executive summary answering the research question.\n" +
|
||||
"5. Note caveats: what's uncertain, what sources were weak, what time-sensitivity applies.\n" +
|
||||
"6. List 2-4 open questions that emerged but weren't answered.\n\nStructured output only.",
|
||||
{ label: "synthesize", schema: REPORT_SCHEMA }
|
||||
)
|
||||
|
||||
if (!report) {
|
||||
// Synthesis skipped/errored — salvage the verified claims raw rather
|
||||
// than throwing on report.findings and discarding the whole run.
|
||||
return {
|
||||
question: QUESTION,
|
||||
summary: "Synthesis step was skipped or failed — returning " + confirmed.length + " verified claims unmerged.",
|
||||
findings: [],
|
||||
confirmed: confirmed.map(c => ({ claim: c.claim, source: c.sourceUrl, quote: c.quote, vote: (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes })),
|
||||
refuted: killed.map(c => ({ claim: c.claim, vote: (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes, source: c.sourceUrl })),
|
||||
sources: allSources.map(s => ({ url: s.url, quality: s.sourceQuality, claimCount: s.claims.length })),
|
||||
stats: { angles: scope.angles.length, sources: allSources.length, claims: allClaims.length, verified: voted.length, confirmed: confirmed.length, killed: killed.length, afterSynthesis: 0 },
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
question: QUESTION,
|
||||
...report,
|
||||
refuted: killed.map(c => ({ claim: c.claim, vote: (c.verdicts.length - c.refutedVotes) + "-" + c.refutedVotes, source: c.sourceUrl })),
|
||||
sources: allSources.map(s => ({ url: s.url, quality: s.sourceQuality, angle: s.angle, claimCount: s.claims.length })),
|
||||
stats: {
|
||||
angles: scope.angles.length,
|
||||
sourcesFetched: allSources.length,
|
||||
claimsExtracted: allClaims.length,
|
||||
claimsVerified: voted.length,
|
||||
confirmed: confirmed.length,
|
||||
killed: killed.length,
|
||||
afterSynthesis: report.findings.length,
|
||||
urlDupes: dupes.length,
|
||||
budgetDropped: budgetDropped.length,
|
||||
agentCalls: 1 + scope.angles.length + allSources.length + (voted.length * VOTES_PER_CLAIM) + 1,
|
||||
},
|
||||
}
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: pilot-protocol
|
||||
description: "Give an AI agent a permanent network address, encrypted P2P messaging, and an installable app store via Pilot Protocol"
|
||||
category: ai-agents
|
||||
risk: critical
|
||||
source: community
|
||||
source_repo: pilot-protocol/pilotprotocol
|
||||
source_type: official
|
||||
date_added: "2026-07-07"
|
||||
author: pilot-protocol
|
||||
tags: [agent-networking, p2p, nat-traversal, overlay-network, agent-apps]
|
||||
tools: [claude, cursor, gemini, codex]
|
||||
license: "AGPL-3.0"
|
||||
license_source: "https://github.com/pilot-protocol/pilotprotocol/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# Pilot Protocol
|
||||
|
||||
## Overview
|
||||
|
||||
Pilot Protocol is an open-source overlay network that gives AI agents first-class
|
||||
network citizenship: a permanent virtual address, encrypted UDP tunnels, NAT
|
||||
traversal, and an explicit per-peer trust model. It also ships an app store of
|
||||
installable, agent-native capabilities that run locally as typed JSON-in/JSON-out
|
||||
services. Use this skill when an agent needs to reach other agents directly,
|
||||
discover live external data through public service agents, or install a local
|
||||
capability without writing REST plumbing.
|
||||
|
||||
If this skill adapts material from an external GitHub repository, it declares:
|
||||
|
||||
- `source_repo: pilot-protocol/pilotprotocol`
|
||||
- `source_type: official`
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when an agent needs a stable address that survives restarts, IP changes,
|
||||
or moving across clouds (no more re-registering webhooks).
|
||||
- Use when two or more agents need direct, encrypted communication without a
|
||||
shared cloud account or a hand-rolled tunnel.
|
||||
- Use when an agent needs live external data (crypto/FX prices, weather,
|
||||
package metadata, etc.) via structured JSON instead of scraping HTML.
|
||||
- Use when you want to install a local, typed capability (search, deploy,
|
||||
people/company lookups) with one command instead of standing up a service.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Install the daemon
|
||||
|
||||
Download the installer, inspect it, then run it — do not pipe it straight into a shell.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://pilotprotocol.network/install.sh -o /tmp/pilot-install.sh
|
||||
less /tmp/pilot-install.sh # review before executing
|
||||
sh /tmp/pilot-install.sh
|
||||
```
|
||||
|
||||
### Step 2: Start the node and confirm it registered
|
||||
|
||||
```bash
|
||||
pilotctl daemon start
|
||||
pilotctl info
|
||||
```
|
||||
|
||||
### Step 3: Query a service agent (no handshake needed)
|
||||
|
||||
Service agents in the public directory auto-approve incoming messages.
|
||||
|
||||
```bash
|
||||
pilotctl send-message list-agents --data '/data {"search":"weather"}' --wait
|
||||
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"
|
||||
```
|
||||
|
||||
### Step 4: Handshake a peer agent for direct messaging
|
||||
|
||||
Peer nodes (as opposed to service agents) require mutual approval before a
|
||||
tunnel works.
|
||||
|
||||
```bash
|
||||
pilotctl handshake <hostname|node_id|address> "<reason>"
|
||||
pilotctl trust
|
||||
pilotctl send-message <peer> --data '<message>'
|
||||
```
|
||||
|
||||
### Step 5: Install and call an agent app
|
||||
|
||||
```bash
|
||||
pilotctl appstore catalogue
|
||||
pilotctl appstore install <app-id>
|
||||
pilotctl appstore call <app-id> <app>.help '{}'
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Ask a live-data service agent
|
||||
|
||||
```bash
|
||||
pilotctl send-message list-agents --data '/data {"search":"bitcoin"}' --wait
|
||||
jq -r '.data' "$(ls -1t ~/.pilot/inbox/*.json | head -1)"
|
||||
```
|
||||
|
||||
### Example 2: Install and call a local capability app
|
||||
|
||||
```bash
|
||||
pilotctl appstore install io.pilot.cosift
|
||||
pilotctl appstore call io.pilot.cosift cosift.answer '{"q":"What is HNSW?"}'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ Use `--wait` on `send-message` so the reply is guaranteed to be in the
|
||||
inbox before you read it.
|
||||
- ✅ Query `list-agents` before guessing a hostname — the catalogue changes.
|
||||
- ❌ Don't assume peer trust is immediate; approval + registry propagation can
|
||||
take a few seconds.
|
||||
- ❌ Don't set `--auto-answer` on your own node — it's a service-agent-only flag.
|
||||
|
||||
## Limitations
|
||||
|
||||
- This skill does not replace reading `pilotctl --help` or the project docs
|
||||
for less common commands.
|
||||
- Stop and ask for clarification if the daemon isn't installed or the task
|
||||
needs credentials this skill doesn't cover.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- The install script fetches an installer from `pilotprotocol.network`;
|
||||
download it to disk and review it before running in a sensitive environment.
|
||||
- `~/.pilot/identity.json` is a private keypair — never copy it between hosts.
|
||||
- Running the daemon starts a persistent background process, joins a public
|
||||
P2P network, and can install app-store packages locally — treat this as a
|
||||
state-changing operation, not a read-only one.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** A `send-message` to a peer silently fails right after a handshake.
|
||||
**Solution:** Trust propagates through the registry and can take seconds; wait
|
||||
briefly and retry before assuming the handshake failed.
|
||||
- **Problem:** Large replies arrive truncated in the inbox JSON.
|
||||
**Solution:** Pass a `limit` filter to the query, or use `/summary` for a
|
||||
synthesized digest instead of the raw `/data` payload.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@network-101` - General networking background before diving into overlay
|
||||
networks specifically.
|
||||
+129
@@ -0,0 +1,129 @@
|
||||
---
|
||||
name: pre-ship-gate
|
||||
description: "A ship gate that runs before any production deploy: checks the silent failure modes that make a deploy 'succeed' while prod stays broken, then verifies the live revision instead of trusting deploy output."
|
||||
category: quality
|
||||
risk: safe
|
||||
source: community
|
||||
source_repo: Sharrmavishal/operating-kit
|
||||
source_type: community
|
||||
date_added: "2026-07-07"
|
||||
author: Sharrmavishal
|
||||
tags: [deployment, quality-gate, verification, ci-cd, production]
|
||||
tools: [claude, cursor, gemini]
|
||||
license: MIT
|
||||
license_source: "https://github.com/Sharrmavishal/operating-kit/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# Pre-Ship Gate
|
||||
|
||||
## Overview
|
||||
|
||||
Most bad deploys do not fail loudly. The pipeline goes green, the CLI prints "deployed", and the old or broken version is still what users hit. This skill is the gate you run right before a production deploy and right after, so an agent stops trusting deploy output and starts confirming what is actually live. It exists because "the deploy command exited 0" and "the new version is serving traffic" are two different facts, and agents routinely confuse them.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use before running any command that pushes to a production or staging environment.
|
||||
- Use when an agent is about to report "shipped", "deployed", or "live".
|
||||
- Use when a deploy reported success but users still see the old behavior.
|
||||
- Use when a release involves database migrations, feature flags, or a staged rollout.
|
||||
|
||||
## How It Works
|
||||
|
||||
The gate has three phases. Do not skip to phase 3.
|
||||
|
||||
### Phase 1: Pre-flight (before the deploy runs)
|
||||
|
||||
Walk the silent failure catalog. These are the modes that let a deploy "succeed" while production stays broken. For each one, confirm it or flag it. Do not assume.
|
||||
|
||||
- **Migrations**: Are schema migrations part of this release, and will they run against the target before the new code serves traffic? A deploy that ships code expecting a column that does not exist yet fails silently for users, not for the pipeline.
|
||||
- **Feature flags**: Is the flag that gates this change actually enabled in the target environment, not just in dev? Shipped code behind an off flag looks like a no-op deploy.
|
||||
- **Build cache / stale assets**: Could a cached build or CDN layer serve the previous bundle after deploy? Confirm the artifact hash or asset fingerprint changed.
|
||||
- **Release pointer**: Does the deploy update the symlink, active revision, or traffic pointer, or does it only upload the new build? Uploading is not releasing.
|
||||
- **Staged rollout / canary**: If traffic is staged, is it stuck at 0 percent or waiting on a manual promote? A canary that never promotes is not a deploy.
|
||||
- **Env and secrets**: Are the env vars and secrets the new code needs present in the target, not just locally? Missing config surfaces as runtime errors, not deploy errors.
|
||||
|
||||
### Phase 2: Run the deploy
|
||||
|
||||
The human or the deploy tooling runs the actual command. This skill does not execute the production deploy itself. It gates it.
|
||||
|
||||
### Phase 3: Verify live (before saying "shipped")
|
||||
|
||||
Confirm the running system, not the deploy log.
|
||||
|
||||
- Fetch the live version or revision identifier from the running service and compare it to the one you intended to ship.
|
||||
- Hit a health or status endpoint and confirm it returns the expected version, not just HTTP 200.
|
||||
- Tail production logs for the first errors after cutover.
|
||||
- Only after the live revision matches the intended revision may you report "shipped". If it does not match, report the mismatch, not success.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Verifying the live revision instead of trusting the deploy log
|
||||
|
||||
```bash
|
||||
# You intended to ship this commit
|
||||
INTENDED="$(git rev-parse --short HEAD)"
|
||||
|
||||
# Ask the running service what it is actually serving
|
||||
LIVE="$(curl -fsS https://your-service.example.com/health | jq -r '.revision')"
|
||||
|
||||
if [ "$INTENDED" = "$LIVE" ]; then
|
||||
echo "Live revision $LIVE matches intended $INTENDED: verified shipped."
|
||||
else
|
||||
echo "MISMATCH: intended $INTENDED but live is $LIVE. Do not report shipped."
|
||||
fi
|
||||
```
|
||||
|
||||
### Example 2: Pre-flight verdict format an agent can emit
|
||||
|
||||
```markdown
|
||||
PRE-SHIP GATE, verdict: HOLD
|
||||
|
||||
- Migrations: 1 pending (add_users_status_col): NOT yet applied to prod. BLOCK.
|
||||
- Feature flags: new_checkout flag is OFF in prod. Enabling required post-deploy.
|
||||
- Build assets: new bundle hash confirmed (a1b2c3 != previous 9f8e7d). OK.
|
||||
- Release pointer: deploy updates active symlink. OK.
|
||||
- Rollout: canary at 10%, manual promote required. NOTE.
|
||||
- Env/secrets: STRIPE_KEY present in prod. OK.
|
||||
|
||||
Reason for HOLD: run migration add_users_status_col before cutover, or the
|
||||
new code will 500 on /orders.
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ Treat "the command exited 0" and "the new version is live" as separate facts, and verify the second one.
|
||||
- ✅ Emit an explicit verdict (SHIP / HOLD) with the failing item named, not a vague "looks good".
|
||||
- ✅ Compare a live revision identifier against the intended one after every deploy.
|
||||
- ✅ Name the specific silent failure mode you are worried about, so a human can override with context.
|
||||
- ❌ Do not report "shipped" from deploy output alone.
|
||||
- ❌ Do not skip the pre-flight because the pipeline is green.
|
||||
- ❌ Do not treat a passing health check as proof the right version is live. Check the version field.
|
||||
|
||||
## Limitations
|
||||
|
||||
- This skill does not run the production deploy for you. It gates and verifies around it.
|
||||
- It cannot know your environment's exact health or version endpoint. Wire in the real one before relying on the verification phase.
|
||||
- The silent failure catalog is common cases, not exhaustive. Systems with unusual release mechanics need their own additions.
|
||||
- It does not replace environment-specific testing, load testing, or expert review.
|
||||
- Stop and ask for clarification if the target environment, the intended revision, or the verification endpoint is unknown.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Health check returns 200 but users still see the old version.
|
||||
**Solution:** The check is hitting a cached edge or the old pod. Verify the revision field in the response, not just the status code.
|
||||
- **Problem:** Migration runs after the new code is already serving traffic.
|
||||
**Solution:** Sequence migrations before cutover, or gate the code path behind a flag until the migration lands.
|
||||
- **Problem:** Deploy "succeeds" but the canary is stuck at 0 percent.
|
||||
**Solution:** Confirm the traffic pointer or promotion step, not just the upload step.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- This skill is defensive and read-oriented. Its own commands are verification calls (fetching a version endpoint, tailing logs, comparing revisions). It does not itself mutate production.
|
||||
- The example commands use `curl -fsS` against a status endpoint and are illustrative. Replace the placeholder host and version field with your own before use.
|
||||
- The actual production deploy is performed by your existing tooling and is out of this skill's scope. Keep human confirmation on the deploy step.
|
||||
- No credentials or tokens are embedded. Do not paste secrets into health-check URLs.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@codebase-audit-pre-push`: clean and audit the code before it ever reaches a deploy.
|
||||
- `@dos-verify-done-claims`: verify a "done" claim against git ground truth after the fact.
|
||||
+175
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: routerbase-model-gateway
|
||||
description: "Integrate RouterBase as an OpenAI-compatible model gateway for routing GPT, Claude, Gemini, media, audio, and embedding requests."
|
||||
category: ai-ml
|
||||
risk: safe
|
||||
source: community
|
||||
source_repo: zenlee123/routerbase-agent-skills
|
||||
source_type: community
|
||||
date_added: "2026-07-07"
|
||||
author: zenlee123
|
||||
tags: [routerbase, llm-routing, openai-compatible, model-gateway]
|
||||
tools: [claude, cursor, gemini, codex, antigravity]
|
||||
license: "MIT-0"
|
||||
license_source: "https://github.com/zenlee123/routerbase-agent-skills/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# RouterBase Model Gateway
|
||||
|
||||
## Overview
|
||||
|
||||
Use [routerbase](https://routerbase.com/) when an application needs one OpenAI-compatible API surface for model routing across GPT, Claude, Gemini, image, video, audio, and embedding workloads. This skill helps agents migrate existing OpenAI SDK calls, document model-selection tradeoffs, and produce safe implementation snippets without exposing credentials.
|
||||
|
||||
RouterBase model availability, pricing, and provider capabilities can change, so treat examples as starting points and verify current catalog data before production recommendations.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when migrating an OpenAI-compatible client to RouterBase by changing the base URL and model ID.
|
||||
- Use when selecting primary and fallback models for chat, reasoning, vision, media generation, audio, or embeddings.
|
||||
- Use when debugging RouterBase request setup, headers, environment variables, streaming, tool calls, JSON mode, or multimodal payloads.
|
||||
- Use when documenting an internal model-routing plan that balances cost, latency, quality, and provider redundancy.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Classify the Workload
|
||||
|
||||
Identify the modality and hard constraints before choosing a model:
|
||||
|
||||
- Modality: chat, vision, image, video, audio, embeddings, or mixed.
|
||||
- Quality target: draft, production, high-stakes review, or automated background task.
|
||||
- Runtime constraints: latency budget, context length, streaming, JSON mode, tool calling, and retry tolerance.
|
||||
- Business constraints: price ceiling, provider preference, regional requirements, and fallback rules.
|
||||
|
||||
### Step 2: Configure the OpenAI-Compatible Client
|
||||
|
||||
Keep the RouterBase API key server-side in an environment variable such as `ROUTERBASE_API_KEY`. Do not put keys in browser, mobile, or public repository code.
|
||||
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key=os.environ["ROUTERBASE_API_KEY"],
|
||||
base_url="https://routerbase.com/v1",
|
||||
)
|
||||
|
||||
response = client.chat.completions.create(
|
||||
model="google/gemini-2.5-flash",
|
||||
messages=[{"role": "user", "content": "Write one sentence about model routing."}],
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
```js
|
||||
import OpenAI from "openai";
|
||||
|
||||
const client = new OpenAI({
|
||||
apiKey: process.env.ROUTERBASE_API_KEY,
|
||||
baseURL: "https://routerbase.com/v1",
|
||||
});
|
||||
|
||||
const response = await client.chat.completions.create({
|
||||
model: "google/gemini-2.5-flash",
|
||||
messages: [{ role: "user", content: "Write one sentence about model routing." }],
|
||||
});
|
||||
|
||||
console.log(response.choices[0].message.content);
|
||||
```
|
||||
|
||||
### Step 3: Validate Model IDs and Capabilities
|
||||
|
||||
When credentials and network access are available, check the live catalog before locking in a model ID or price-sensitive recommendation.
|
||||
|
||||
```bash
|
||||
curl "https://routerbase.com/api/v1/models?task=chat" \
|
||||
-H "Authorization: Bearer $ROUTERBASE_API_KEY"
|
||||
```
|
||||
|
||||
Confirm feature assumptions with a small request fixture:
|
||||
|
||||
- Streaming works when `stream: true` is set.
|
||||
- Tool calling accepts the exact schema used by the app.
|
||||
- JSON mode returns parseable output and still passes application validation.
|
||||
- Vision or media payloads use the expected OpenAI-compatible content shape.
|
||||
|
||||
### Step 4: Design Fallbacks Conservatively
|
||||
|
||||
Use explicit application-level fallbacks unless the user's RouterBase account already has a smart-routing policy configured.
|
||||
|
||||
```js
|
||||
const modelPlan = [
|
||||
"anthropic/claude-sonnet-4-6",
|
||||
"google/gemini-2.5-flash",
|
||||
];
|
||||
|
||||
for (const model of modelPlan) {
|
||||
try {
|
||||
return await client.chat.completions.create({ model, messages });
|
||||
} catch (error) {
|
||||
if (!isRetryableRouterBaseError(error)) throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Treat transient network errors, timeouts, rate limits, and server errors as candidates for retry. Do not blindly retry authentication failures, invalid model IDs, validation errors, or policy refusals.
|
||||
|
||||
## Examples
|
||||
|
||||
### Migration Checklist
|
||||
|
||||
When converting an existing OpenAI SDK integration:
|
||||
|
||||
1. Change the base URL to `https://routerbase.com/v1`.
|
||||
2. Read `ROUTERBASE_API_KEY` from server-side environment configuration.
|
||||
3. Replace the model name with a RouterBase model ID that matches the task.
|
||||
4. Preserve standard OpenAI request fields unless RouterBase documentation says otherwise.
|
||||
5. Run one minimal smoke test before shipping.
|
||||
|
||||
### Routing Plan Format
|
||||
|
||||
Use this table when recommending a model strategy:
|
||||
|
||||
| Use case | Primary model | Fallback model | Reason | Validation |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Support chat | Provider/model ID | Provider/model ID | Low latency and acceptable quality | Streaming smoke test |
|
||||
| Deep analysis | Provider/model ID | Provider/model ID | Strong reasoning, higher cost acceptable | Eval prompt plus human review |
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Do keep RouterBase keys in server-side environment variables or secret managers.
|
||||
- Do verify current model availability and pricing before production decisions.
|
||||
- Do document primary and fallback model assumptions in the code or runbook.
|
||||
- Do validate structured outputs with application schemas.
|
||||
- Do not paste, log, commit, or screenshot real API keys.
|
||||
- Do not hard-code model pricing or provider availability as permanent facts.
|
||||
- Do not expose RouterBase keys in client-side JavaScript, mobile apps, or public repos.
|
||||
|
||||
## Limitations
|
||||
|
||||
- This skill does not replace RouterBase account configuration, live model catalog checks, or production observability.
|
||||
- Some model features are provider-specific and must be tested with the exact selected model.
|
||||
- High-stakes outputs still require human review and domain-specific evaluation.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- Treat RouterBase credentials as production secrets.
|
||||
- Mask tokens in logs and support tickets.
|
||||
- Ask for explicit user approval before running live API calls that consume credits.
|
||||
- Use placeholders such as environment variables in examples; never invent or include realistic secret strings.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** The code works with one provider but fails after switching models.
|
||||
**Solution:** Re-test tool calling, JSON mode, streaming, and multimodal payloads for each selected model.
|
||||
|
||||
- **Problem:** Fallback logic retries non-retryable errors.
|
||||
**Solution:** Retry only transient failures and fail fast on authentication, validation, and invalid model errors.
|
||||
|
||||
- **Problem:** A model recommendation becomes stale.
|
||||
**Solution:** Re-check the RouterBase catalog and pricing page before finalizing the plan.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@api-analyzer` - Use when the task is only to validate one API request shape.
|
||||
- `@langfuse` - Use when the task needs production LLM observability, tracing, and evaluation.
|
||||
+218
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: tree-ring-memory
|
||||
description: "Use Tree Ring Memory for local-first AI-agent memory lifecycle work: recall, evidence, audit, forgetting, and consolidation without transcript dumping."
|
||||
category: development
|
||||
risk: safe
|
||||
source: community
|
||||
source_repo: TerminallyLazy/Tree-Ring-Memory
|
||||
source_type: community
|
||||
date_added: "2026-07-08"
|
||||
author: TerminallyLazy
|
||||
tags: [agent-memory, local-first, recall, privacy, codex, sqlite, cli]
|
||||
tools: [claude, codex, cursor, gemini, antigravity, opencode]
|
||||
license: "Apache-2.0"
|
||||
license_source: "https://github.com/TerminallyLazy/Tree-Ring-Memory/blob/main/LICENSE"
|
||||
---
|
||||
|
||||
# Tree Ring Memory
|
||||
|
||||
## Overview
|
||||
|
||||
Tree Ring Memory is a framework-agnostic, local-first memory lifecycle layer for
|
||||
AI agents. Use this skill when an agent should recall, preserve, audit, or
|
||||
forget durable project memory without treating raw conversation transcripts as
|
||||
memory.
|
||||
|
||||
The public runtime is a Rust CLI/TUI with local SQLite/FTS storage, scoped
|
||||
recall, evidence records, audit, deterministic consolidation, maintenance,
|
||||
DOX/Revolve source adapters, framework discovery, redaction, and explicit
|
||||
forgetting.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use before resuming a project where prior decisions, warnings, preferences,
|
||||
or failed approaches may matter.
|
||||
- Use before changing architecture, storage, security, privacy, release, or
|
||||
agent-memory behavior.
|
||||
- Use when the user asks to remember, recall, audit, redact, forget, or
|
||||
consolidate agent memory.
|
||||
- Use after tests, reviews, incidents, or production behavior validate a lesson
|
||||
future agents should preserve.
|
||||
- Use when a project contains `.tree-ring/SKILL.md`, `.tree-ring/CLI.md`, or
|
||||
other Tree Ring bridge files.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Discover Local Guidance
|
||||
|
||||
Check whether the current project already has Tree Ring guidance:
|
||||
|
||||
```bash
|
||||
test -f .tree-ring/SKILL.md && sed -n '1,220p' .tree-ring/SKILL.md
|
||||
test -f .tree-ring/CLI.md && sed -n '1,220p' .tree-ring/CLI.md
|
||||
```
|
||||
|
||||
Treat project-local `.tree-ring` files as more authoritative than generic
|
||||
examples in this skill. If the CLI is installed, inspect the current command
|
||||
surface before assuming flags:
|
||||
|
||||
```bash
|
||||
tree-ring --help
|
||||
tree-ring recall --help
|
||||
tree-ring remember --help
|
||||
tree-ring evidence --help
|
||||
tree-ring audit --help
|
||||
tree-ring forget --help
|
||||
```
|
||||
|
||||
If Tree Ring is not installed, do not run remote installer commands
|
||||
automatically. Point the user to the project repository or install docs and ask
|
||||
whether they want installation help.
|
||||
|
||||
## Step 2: Recall Before Risky Work
|
||||
|
||||
Use narrow, project-scoped recall first:
|
||||
|
||||
```bash
|
||||
tree-ring recall "release behavior" --scope project
|
||||
tree-ring recall "sqlite migration" --scope project
|
||||
tree-ring recall "user preference" --scope global
|
||||
```
|
||||
|
||||
Use recalled memory as context, not authority. Verify it against current source
|
||||
files, tests, docs, issues, pull requests, logs, and runtime state before making
|
||||
changes.
|
||||
|
||||
## Step 3: Write Only Durable Memory
|
||||
|
||||
Write concise memory only when it is likely to help future agents:
|
||||
|
||||
```bash
|
||||
tree-ring remember "Run project-scoped recall before release changes." --event-type lesson --scope project
|
||||
```
|
||||
|
||||
Prefer specific event types when supported locally:
|
||||
|
||||
- `decision`
|
||||
- `lesson`
|
||||
- `warning`
|
||||
- `correction`
|
||||
- `user_preference`
|
||||
- `tool_result`
|
||||
- `summary`
|
||||
- `hypothesis`
|
||||
|
||||
Store the durable lesson, decision, warning, or follow-up. Do not store the
|
||||
full conversation.
|
||||
|
||||
## Step 4: Record Evidence for Evaluated Outcomes
|
||||
|
||||
Use evidence records for test runs, incidents, reviewed changes, or other
|
||||
evaluated outcomes:
|
||||
|
||||
```bash
|
||||
tree-ring evidence \
|
||||
--outcome observed \
|
||||
--summary "Installer smoke test passed in an isolated HOME." \
|
||||
--evidence-ref "ci/install-smoke/2026-07-08"
|
||||
```
|
||||
|
||||
Outcome guidance:
|
||||
|
||||
- `promoted`: durable truth backed by strong evidence
|
||||
- `rejected`: failed or rolled-back approach worth keeping visible
|
||||
- `deferred`: unresolved idea or future option
|
||||
- `observed`: normal evaluated result
|
||||
|
||||
Do not promote weak, stale, or unreviewed claims to durable truth.
|
||||
|
||||
## Step 5: Use Source Adapters Carefully
|
||||
|
||||
When a repo has structured source records, run dry runs first:
|
||||
|
||||
```bash
|
||||
tree-ring dox sync --source-root . --dry-run
|
||||
tree-ring revolve sync --source-root revolve --dry-run
|
||||
tree-ring integrations scan --source-root .
|
||||
```
|
||||
|
||||
Only write adapter summaries when they are concise, source-linked, useful, and
|
||||
privacy-safe. Imported memory does not replace the underlying `AGENTS.md`,
|
||||
Revolve record, test, pull request, issue, or documentation.
|
||||
|
||||
## Ring Selection
|
||||
|
||||
Use the smallest durable ring that fits:
|
||||
|
||||
- `cambium`: active or recent task context
|
||||
- `outer`: recent decisions and task lessons
|
||||
- `inner`: older compressed project knowledge
|
||||
- `heartwood`: durable high-confidence truths
|
||||
- `scar`: failures, regressions, rejected approaches, warnings
|
||||
- `seed`: unresolved ideas, hypotheses, follow-ups
|
||||
|
||||
Prefer `outer` or `seed` unless the user confirms durability or the evidence is
|
||||
strong.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Recall before risky or repeat work.
|
||||
- Keep project memory project-scoped unless it is a durable cross-project user
|
||||
preference.
|
||||
- Attach source references such as file paths, issue ids, PR ids, evaluation
|
||||
runs, or docs paths.
|
||||
- Re-check current source files and runtime state before acting on recalled
|
||||
memory.
|
||||
- Ask at closeout what future agents should remember, avoid, or revisit.
|
||||
- Use redaction, deletion, or supersession when memory is wrong, stale,
|
||||
sensitive, or replaced by a newer decision.
|
||||
|
||||
## Security & Safety Notes
|
||||
|
||||
- Never use Tree Ring Memory as a hidden recorder.
|
||||
- Do not store secrets, credentials, tokens, private keys, recovery codes, raw
|
||||
chain-of-thought, or temporary scratchpad content.
|
||||
- Do not store sensitive personal data unless the user explicitly asks and the
|
||||
retention boundary is safe.
|
||||
- Do not store copyrighted source text beyond short allowed excerpts.
|
||||
- Do not run installer, network, destructive, or mutation commands without
|
||||
explicit user approval and a clear target environment.
|
||||
- Treat all examples as commands to adapt after checking local `--help`, not as
|
||||
guaranteed command surfaces.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Tree Ring Memory is not a replacement for source control, issue trackers,
|
||||
documentation, tests, logs, or live runtime verification.
|
||||
- Recalled memory can be stale or wrong. Always verify important claims against
|
||||
the current project before using them to make changes.
|
||||
- The CLI surface can change across releases. Prefer local `.tree-ring`
|
||||
guidance and `tree-ring --help` over copied command examples.
|
||||
- It should not be used for secret storage, comprehensive transcript archives,
|
||||
compliance retention, or unreviewed collection of sensitive personal data.
|
||||
- Cross-agent interoperability depends on each tool's ability to call the local
|
||||
CLI or read project-local guidance files.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Recalled memory conflicts with current source.
|
||||
**Solution:** Treat source files, tests, docs, and runtime evidence as
|
||||
authoritative; supersede or forget stale memory.
|
||||
|
||||
- **Problem:** Memory starts becoming transcript storage.
|
||||
**Solution:** Store only durable decisions, warnings, preferences, outcomes,
|
||||
and follow-ups.
|
||||
|
||||
- **Problem:** A lesson is useful but contains sensitive detail.
|
||||
**Solution:** Store a redacted summary or do not store it.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@agent-memory-systems` - Use for broad agent-memory architecture choices.
|
||||
- `@agent-memory` - Use for the listed hybrid memory MCP system.
|
||||
- `@planning-with-files` - Use when simple persistent files are enough.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- Tree Ring Memory repository: <https://github.com/TerminallyLazy/Tree-Ring-Memory>
|
||||
- Codex plugin wrapper: <https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin>
|
||||
Reference in New Issue
Block a user