skills/getcargohq__cargo-skills
1
0
Fork 0
mirror of https://github.com/getcargohq/cargo-skills.git synced 2026-09-14 19:17:15 +08:00
Code Issues Packages Projects Releases Wiki Activity
167 Commits 109 Branches 0 Tags
docs/script-require-allowlist
Commit Graph

4 Commits

Author SHA1 Message Date
Auree Aubert aead4ddc20 Search for actions, and config stopped shouting (#115) 
* Cargo has a first-party MCP, and `config` stopped shouting

Tracks the platform-MCP branch in the CLI repo: a first-party MCP server at
`/mcp`, a new `orchestration action list`, and `config` split off the top-level
action type. Two of those three contradict sentences this bundle stated as fact.

- The router, `cargo-ai`, and the glossary all said there is no first-party
  Cargo MCP server. There is one now, at `mcp.getcargo.io/mcp`, with a fixed
  operate-the-workspace toolset. Both surfaces — platform and curated — are
  documented, and the routing rule they exist for is unchanged.
- `cargo-ai mcp` with no `--server` now bridges the platform MCP rather than
  resolving "the workspace's only MCP server". Same command, different server
  by CLI version, so it is in the gotchas table.
- New `orchestration action list <keywords>`: free, searches connector, native,
  tool, and agent actions in one call, and returns a ready `action` object with
  `connectorUuid` resolved plus the action's credit costs.
- `config` is optional on execute/execute-batch and still required on nodes,
  alerts, play health actions, and get-output-schema. The dangerous half is the
  deleted guard: misplaced inputs are now dropped silently and the action runs
  with none.
- Nine documents were telling agents to do exactly that. The four LLM playbooks,
  the prompt-library index, and three GTM recipes put `model`/`advancedSettings`/
  `output` (or `customerId`, `spreadsheetId`) in the action's `config`; all now
  put inputs in `--data`/`--records`. The ads recipe also loses two
  `execute-batch --model-uuid --filter` calls against flags that do not exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

Co-authored-by: Auree Aubert <aureeaubert@users.noreply.github.com>

* Drop `config` from every top-level action, and lead with action search

The platform-MCP work shipped while this PR was open — CLI 1.0.66 is on npm and
the platform MCP answers at mcp.getcargo.io/mcp — so the hedging this branch was
written with ("newer backends accept…", "stays valid on any version") is now
just the rule.

- `config` is gone from 272 execute / execute-batch examples across 79 files.
  That is the shape `action list` returns, so a search result pastes straight
  into a run. Nodes, alert `--actions`, play `healthAlertActions`, and agent /
  MCP-server `--actions` keep theirs; the strip was scoped around them.
- `get-output-schema` is the exception and still requires `config` — verified
  live: the action object from `action list` fails 400 at `action.config`. The
  CLI's own help examples for that command omit it and therefore all 400. It is
  now a gotcha row, and those examples keep `"config": {}` on purpose.
- `connection action search` shipped in 1.0.36 and no skill had ever mentioned
  it. cargo-connection now opens with both searches and a table for choosing:
  `action list` by default, `action search` for `--credits-only` and
  `--category`. `integration list` / `integration get` drop to what they are
  good at — the integration, and the schema of an action already picked.
- Removed a phantom command: `connection integration list-actions` has never
  existed, and cost-discipline.md was recommending it as a free lookup.
- cargo-mcp gains the one config rule that surface needs: pass the action object
  as-is, never with a config — `get_action_schema` supplies the empty one, which
  makes MCP safer here than the CLI.

Verified against the live workspace at 1.0.66: a config-less `action execute`
returns status success at 0 credits, and `get-output-schema` without `config`
returns 400.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

* Fix the strip's leftovers, and bump the router so it actually ships

An audit of the 272-example strip turned up one real defect and a set of
phrasings the strip left behind, plus a packaging bug that would have made the
router's half of this PR a no-op.

- `cargo/SKILL.md` was still at 1.22.0, the version main already publishes, so
  its 14 changed lines — including both new critical rules and both new gotcha
  rows — would have been skipped at publish. Bumped to 1.23.0, plugin manifests
  follow.
- `guides/writing-outreach.md` still declared the action shape as
  `integrationSlug + actionSlug + config: {}` directly above an example whose
  config had been stripped. Every sibling "Action shape" line had been rewritten;
  this one was missed.
- Seven places said the action's config "is empty" or "stays empty" where the
  rule is now that there is no config key at all. Normalised, including the
  deliberate contrast in cargo-observability, where alert actions do require one.
- The report template in cargo-workspace-management modelled the old shape in a
  copyable `action execute` string, and cited `config.portalId required` as the
  symptom. Both corrected.
- perplexity's `searchContextSize` is an input, not a "config cost lever" — the
  same rewrite had moved it into `advancedSettings` in `--records`.

Verified clean afterwards: no execute example retains a config, no
get-output-schema example lost one, no node/alert/agent/mcp-server action lost
one, and every JSON block still parses.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TBfa73ishJJRe4pccyhTAa

---------

Co-authored-by: Auree Aubert <aureeaubert@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-27 16:42:39 -07:00
Auree Aubert 3708f8c955 Agent discoverability: trigger-shaped descriptions, routing evals, standalone bootstrap (#77) 
* Agent discoverability: trigger-shaped descriptions, routing evals, standalone bootstrap

The `description` field is the only text an agent weighs before deciding
whether to load a skill. Everything else in the bundle is invisible until
that decision is already made — and twelve of the seventeen descriptions
read as "Manage <CLI nouns> using the Cargo CLI", which matches a user who
is already thinking in Cargo's object model rather than one stating a job.

This rebuilds that layer and, for the first time, tests it.

Routing
- Every description rewritten to a four-part template: job in the user's
  words -> literal quoted trigger phrases -> proper nouns -> an explicit
  `Skip when:` pointing at the sibling skill that owns the adjacent case.
- Integration and provider names are generated, not hand-maintained.
  sync-trigger-slugs.ts fills cargo-gtm's `Providers:` list from the
  playbook tree and cargo-connection's `Integrations:` list from a
  committed catalog snapshot (138 integrations, 50 credits-based).
  `--refresh` re-pulls from a logged-in CLI; `--check` gates CI.
- evals/routing.jsonl (92 prompts) + routing-eval.ts, wired into CI.
  Structural tier asserts the template and that each skill keeps >=5 terms
  unique to it; lexical tier requires the expected skill to rank first;
  an opt-in --llm tier asks a real model to route from descriptions alone.
  Deep paraphrases are tagged "hard" and reported rather than gated — a
  lexical proxy cannot judge them fairly.

Standalone installs
- `skills add --skill <one>` is a supported path and the registry lists
  each skill separately, but thirteen skills' only install instructions
  were a relative link to ../cargo/references/prerequisites.md, which does
  not exist in a single-skill install. Every SKILL.md now has a
  self-contained Bootstrap section, enforced by the linter.

Coverage
- New capability skill cargo-segmentation — the segmentation CLI domain,
  previously uncovered while segments were load-bearing in most recipes.
  Verified against the live CLI, including the flag traps.
- Three cargo-gtm recipes: source-planning (probe and cost candidate
  sources per *hit* before any fan-out), ads-audience-activation (Google
  Customer Match / LinkedIn Matched Audiences), review-and-iterate (human
  review of judgment output, kept as an eval set).
- Router gains a "these skills vs a workspace MCP server" section: Cargo
  has no first-party MCP server — a workspace builds one and serves it
  over `cargo-ai mcp` — so the routing rule is scale and reproducibility.

Index and hygiene
- llms.txt now lists every recipe and provider playbook with a generated
  summary: 17 entries -> ~80 job-named addressable URLs.
- Router trimmed ~80 lines of per-skill summaries that restated each
  skill's own description; critical rules kept in full.
- Linter: bootstrap check, skill-count claims validated against the tree,
  `doctor` and `mcp` added to the known CLI domains.
- CONTRIBUTING.md, keyword-dense README opening, updated repo metadata.

Also carries the aiArk/apolloio priority-stack promotion authored in a
parallel session on this branch (cargo-gtm 1.12.0) — the two touch the
same SKILL.md files and could not be split cleanly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Surface the 100-credit free tier where an agent meets it

There is no purchase gate between installing Cargo and producing a real
deliverable — a new account starts with 100 free credits and no card — and
nothing in the bundle said so. An agent that doesn't know the budget can't
tell a first-time user whether the demo is a look around or a commitment,
and defaults to hedging.

Now stated at every point an agent encounters the question:

- README opening and the generated llms.txt install block: an agent can
  install, sign the user up, and hand back a list in one turn.
- Router install section and prerequisites.md, with anchors for what 100
  credits buys (~5,000 sourced leads, ~1,000 verified-email enrichments,
  ~50 fully enriched contacts).
- cargo-quickstart: the demo spends ~0.5 of the 100, and the skill now
  says so before the first paid call — that reframes the moment from a
  purchase decision into a look around, which is the job of a quickstart.
- cargo-billing: a "what 100 credits buys" table, plus two new trigger
  phrases so free-tier questions route here at all.
- cost-discipline.md: on a new account, receipts and next-step proposals
  must be framed against the free tier. "87.6 of your 100 free credits
  left" is a number the user can act on; "87.6 remaining" is not. Also
  warns that phone lookups (6-7/call) are the fastest way to burn a tier
  a first session should end with something left to try.

Two routing eval cases added for free-tier questions (79/79 core).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Run the routing evals against a real model in CI

The lexical tier passes 79/79, but it is a deterministic proxy written
alongside the descriptions it grades — it cannot fail in a way that
surprises us, which is what makes it weak evidence. The only honest
scoreboard for the description rewrite is whether a real model, shown
nothing but the 17 descriptions, routes the eval prompts correctly.

That tier existed but had never run. Now it does, in its own workflow.

- New .github/workflows/routing-evals-llm.yml, using the repo's
  ANTHROPIC_API_KEY. Deliberately not part of skills-lint: it costs money
  and is non-deterministic, so it must never stand between a typo fix and
  a merge. Triggers on PRs and pushes that touch a SKILL.md, the eval
  cases, or the runner; weekly on a schedule so model drift surfaces even
  when nobody edits a description; and on demand with a model override.
- runLlm reworked for CI: 6-way concurrency (92 sequential calls is a slow
  job), retry with backoff on 429/5xx, tolerant answer parsing, and a
  core/hard/overall breakdown instead of one number.
- Results are written to GITHUB_STEP_SUMMARY as a table, including every
  misroute with what the model picked instead — so a regression is
  readable on the run page without opening logs.
- Optional --llm-min=<percent> floor, wired to the exit code. Left unset
  until the first runs establish a baseline; a floor guessed before the
  data would either never fire or block on noise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Act on the first real-model routing run: 92/94, two fixes

Baseline from the model tier (claude-haiku-4-5, judging from the 17
descriptions alone): 92/94 overall — core 79/79, hard 13/15. The lexical
proxy's 3/15 on the hard tier was noise about the proxy, not the
descriptions, which is what that tier existed to establish.

Both misroutes were worth having:

- "Our outbound is going to the wrong people — help me figure out who
  actually buys from us" routed to cargo-context instead of cargo-gtm.
  A real collision: cargo-context's triggers include "who do we sell to",
  which reads as ICP ownership. It owns *writing the conclusion down*;
  deriving it from won/lost data is cargo-gtm. Added that boundary to
  cargo-context's Skip when, and the two phrasings to cargo-gtm.

- "Give the assistant access to our sales collateral so it stops making
  things up" routed to cargo-content instead of cargo-ai — and the model
  was right. As written the first step is getting the collateral into the
  workspace. Corrected the expectation and added the other side of the
  boundary as its own case ("attach the library we already uploaded to
  the agent"), which the lexical tier then failed, correctly: cargo-ai
  never said "library" or "release resources". Added both, so the
  content/ai split is now legible to a ranker and a model.

Set --llm-min=93 now that a baseline exists. Deliberately below the
observed 98%, not at it: a model tier that fails on one non-deterministic
flip trains people to ignore it.

Lexical 80/80 core.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Document cargo-ai mcp — the bridge that was written down nowhere

Cargo reaches coding agents through two doors. Skills reach agents that
implement skills.sh; a workspace MCP server reaches everything else —
Claude Desktop, ChatGPT, and whatever ships next. The second door was
fully built and documented in exactly one place: `cargo-ai mcp --help`.

Worse, cargo-ai/SKILL.md taught `ai mcp-server create` (building a server)
without ever mentioning the command that serves it, so an agent could
construct one and have no idea how to connect it — and the section
conflated publishing a server with consuming someone else's, which are
unrelated surfaces.

- MCP section rewritten around the two directions, with a table: publish
  (`ai mcp-server`, called by any MCP client, wired via `cargo-ai mcp`)
  vs consume (`ai mcp-client`, called by your agents, wired via
  `release update-draft --mcp-clients`). States plainly that there is no
  first-party Cargo MCP server — a workspace builds its own.
- Documents `cargo-ai mcp` with the registration one-liner, the
  CARGO_MCP_SERVER_UUID fallback, and the stdout-is-protocol constraint.
- Details verified against the live API rather than --help: actions take
  kind "tool" *or* "agent" (an agent is exposable as a callable MCP
  tool), resources take model or file, and `update` replaces the arrays
  wholesale instead of merging — a real footgun.
- Routing rule for which door to use, pointing at the router section.
- Two trigger phrases ("expose our tools as an MCP server", "use Cargo
  from Claude Desktop or ChatGPT") and two eval cases, so the publish
  direction is reachable from a description at all. It previously wasn't.

Lexical 81/81 core.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-12 10:18:32 -07:00
replicas-connector[bot] e28aabd521 Point the skills at browserless login, and unpin agents from a CLI that lacks it (#73) 
* Point the skills at browserless login, and unpin agents from a CLI that lacks it

cargo-ai 1.0.47 (2026-08-10) added `login --email`: it mails a one-time code,
creates the account on first use, and needs no browser at any point. All 16
skills still described sign-in as "browser sign-in via --oauth, or an API
token".

The load-bearing change is `cargo/cli-version`. The router tells every agent to
run `npm install -g @cargo-ai/cli@$(cat cli-version)` at session start, and that
pin was 1.0.29 (2026-07-09). Its `login` command exposes only --oauth, --token
and --workspace-uuid, so documenting --email without moving the pin would ship a
flag the installed binary does not have.

- cargo/cli-version: 1.0.29 -> 1.0.47
- 16 compatibility lines rewritten
- router + README install blocks lead with --email, and name the agent-shell
  behaviour (no terminal: first call sends the code and exits, re-run with
  --code) and the stdin form
- patch version bump on each changed SKILL.md so clawhub republishes them

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

* Regenerate skill-metadata.json for the changed skills

The bundle linter tracks a version and a contentHash per skill and failed with
19 stale entries. Regenerated with the documented command, so the diff is only
the bumped versions and their matching hashes.

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

* Mirror the router version bump into the three plugin manifests

The linter requires .claude-plugin, .codex-plugin and .cursor-plugin to carry
the router's version. 1.17.0 -> 1.17.1.

Co-Authored-By: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
Co-Authored-By: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>

---------

Co-authored-by: replicas-connector[bot] <replicas-connector[bot]@users.noreply.github.com>
Co-authored-by: Auree Aubert <16732193+aureeaubert@users.noreply.github.com>
 2026-08-11 14:42:02 -07:00
Auree Aubert f6d752d869 Add cargo-observability skill — scheduled threshold alerts (#72) 
* Add cargo-observability skill for the alerts domain

Introduces a new capability skill documenting the observability CLI
domain (cargo-ai observability alert/event) shipped in the backend/api.

Alerts are scheduled threshold checks: measure a scope (spans/runs/
records/orchestrationQuery/storageQuery/model), compare to a threshold
(metric + gte/lte + value), and fire actions as runs on breach.

New skill: cargo-observability/
  - SKILL.md — commands, the preview-before-create discipline, the
    scope/threshold/action model, permissions, and cost discipline
  - references/scopes-and-thresholds.md — the scope↔threshold matrix,
    metric meanings/units, and the empty-window-vs-real-zero rule
  - references/alert-lifecycle.md — cron windows, at-most-once firing,
    dead-man's switches, and the {{alert.*}}/{{event.*}} templating
  - references/examples/recipes.md — seven copy-paste alert recipes

Pack integration:
  - Router cargo/SKILL.md → 1.17.0: table row, recap, dependency rule,
    diagram box, defineAlert added to the CDK builder list, counts
    (15→16 skills; twelve→thirteen capability skills)
  - README.md, AGENTS.md: counts + Observability capability row + a
    "get alerted when something breaks" use case
  - Plugin manifests bumped to 1.17.0 to mirror the router
  - skills-lint.mjs: cargo-observability in SKILL_DIRS, observability
    in the known-CLI-domains allowlist
  - CHANGELOG entries; regenerated skill-metadata.json

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017UzK9huhSm588ThVFS1GcE

* Document defineAlert in the cargo-cdk skill

Wires the new observability domain into the declarative skill so alerts
can be managed as workspace-as-code, not only via the imperative CLI.

cargo-cdk → 1.2.0:
  - references/resources.md: defineAlert Builders-table row + a "Notes on
    specific fields" entry — the scope↔threshold matched pair (TS narrows
    the metric menu by scope.kind), scope wiring by handle, the {ref,config}
    action wrapper + alertConnectorAction/alertToolAction helpers +
    {{event.*}}/{{alert.*}} templating, and the slugless-identity note
  - guides/authoring-resources.md: an Observability example wiring an alert
    to a definePlay handle with an agent action
  - SKILL.md §6: alert added to the slugless "commit cargo.state.json"
    resources; new critical rule that a defineAlert whose actions call paid
    nodes re-bills on every breach (preview the threshold; prefer cheap
    notification actions); cross-links to cargo-observability

Also: cargo-observability scopes reference now states telemetry duration is
in seconds (confirmed authoritative from the CDK builder types).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017UzK9huhSm588ThVFS1GcE

---------

Co-authored-by: Claude <noreply@anthropic.com>
 2026-08-09 15:57:34 -07:00