skills/tinyfish-io__tinyfish-cookbook
1
0
Fork 0
mirror of https://github.com/tinyfish-io/tinyfish-cookbook.git synced 2026-09-14 17:41:39 +08:00
Code Issues Packages Projects Releases Wiki Activity
191 Commits 5 Branches 0 Tags
main
Commit Graph

6 Commits

Author SHA1 Message Date
London Dávila d58743b5eb Doctor skill: track schema_version 3, quote the gh issue title, list ~/.grok (#262) 
doctor still described `schema_version` 1 and 2 + bailed above 2, but
CLI emitted 3 since 0.22.0 and skill pins `@tiny-fish/cli@latest`. as
shipped it degraded to `--pretty` on every run. The feedback skill also
passed an unquoted, user-derived title to `gh issue create`. three fixes
landed in tinyfish-web-agent-integrations#29; this keeps the two copies
of the plugin textually identical

- `doctor`: schema 3 — `cli_version`, `ok_harnesses`/`ok_cli`,
`checks[].scope`, `repairs[].action`, and the exit code coming from the
harness scope alone, so `ok_cli: false` beside exit `0` is a real state.
Drops the `registered, API key present but unverified` string the CLI no
longer emits; `--fix` examples run through `npx` like step 1.
- `feedback`: `--title "$title" --body-file "$body_file"`, injection
warning widened to the title, and `eval` / constructed command strings
prohibited.
- `plugins/tinyfish/README.md`: adds `~/.grok` to the config dirs doctor
reads, per the CLI's `CONFIG_DIRS`. The rest of that list matches.
- 1.2.3 → 1.2.4 in `plugin.json` and the marketplace entry —
`validate-skills.mjs` fails if they diverge

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-26 15:45:11 -06:00
Zachary Lyon 2751ef7662 Doctor skill: teach it schema_version 2 rather than bail on it (PF-3584) (#256) 
Ships plugin **v1.2.3**. Rebased onto `main` now that #252 has
squash-merged, so this is a single commit.

## Why this is now urgent rather than cosmetic

1.2.2 added a forward guard:

> Read `schema_version` before the fields. This skill describes `1`.
[...] on anything other than `1`, stop reading fields, show the user
`--pretty` output instead, and rely on step 2 for the verdict.

Good instinct, but the CLI shipping PF-3618 (ux-labs#4334) stamps
`schema_version: 2`. The skill pins `@latest`, so **the moment that CLI
publishes, that guard degrades every user to `--pretty` and drops
`repairs[]` entirely.** This PR teaches the skill the new version
instead: the guard now covers `1` and `2` and bails only above `2`.

## What the two versions actually differ on

#252's own "Upstream CLI issues found" list opened with:

> registration detection reports key **presence, not validity** — a
stale key header passes as `registration: PASS` while every call 401s

That is what `2` fixes. So:

| | |
|---|---|
| `1` | a keyed registration passes on config presence. Step 2 is the
only thing that catches a stale key |
| `2` | it was tested on the wire, so a stale key header is already a
`fail` with a `connect` repair beside it |

Step 2 keeps its job either way: OAuth harnesses, `auth_mode: unknown`
(every plugin install), and the sibling-server problem #252 fixed are
all untouched by the CLI change.

## Three smaller consequences of the same CLI change

- **`warn` needed saying out loud.** A keyed registration whose value
doctor cannot read reports "API key present but unverified", which is
every Codex install (it reports api-key from an env var name doctor
cannot resolve). It does not move the exit code and must not be
repaired.
- **`repairs[]` order is load-bearing.** `auth login` precedes
`connect`, because `connect` writes whichever key is stored and a dead
one has to be replaced first.
- **Cursor's unattended repair has a different gate than 1.2.2 states.**
1.2.2 says "while the CLI's own credential resolves". On `2` it is the
CLI's *authenticated call* passing: a revoked key resolves as a
credential perfectly well and still cannot write a working header.

## Verified

`node scripts/validate-skills.mjs` passes: generated variants in sync
with `skills-src/`, frontmatter under the 1024-char Codex limit,
marketplace entry and `plugin.json` both at 1.2.3.

## Sequencing

Safe to merge before the CLI publishes: the skill reads `schema_version`
at runtime and both branches are correct. Merging it *after* the CLI
publishes leaves a window where installed copies bail to `--pretty`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-17 15:42:25 -04:00
London Dávila 074962c11a TinyFish setup + skills: doctor/feedback skills, generator, CI validation, INSTALL.md (#252) 
Ships plugin **v1.2.2** to the Claude Code marketplace. `main` serves
v1.1.0, which has no doctor/feedback skills at all — the first coworker
install got the stale version because the marketplace serves the default
branch.

## What changed since the original review

The CLI now ships `tinyfish doctor` — structured JSON, exit codes,
`--fix`. The skill used to re-implement those checks by hand; it now
runs the CLI for them and keeps only the job the CLI structurally cannot
do.

| | |
|---|---|
| Was | 4 hand-rolled checks + repair table + report allowlist |
| Now | run `doctor`, read `checks[]`/`repairs[]`, then prove harness
reach with a real MCP call |

`provesHarnessReach` requires `authMode === "api-key"`, so it is **false
for every OAuth harness** — the CLI cannot borrow the harness's token.
Closing that gap is the whole skill.

## Contents

| Path | |
|---|---|
| `skills-src/` | single source for doctor + feedback |
| `scripts/generate-harness-skills.mjs` | per-target substitution;
targets opt in per file |
| `plugins/tinyfish/skills/{doctor,feedback}/` | Claude Code variant
(`/tinyfish:doctor`) |
| `skills/tinyfish-doctor/` | generic variant — `npx skills add
tinyfish-io/tinyfish-cookbook --skill tinyfish-doctor` |
| `.github/workflows/validate-skills.yml`, `scripts/validate-skills.mjs`
| frontmatter validity (≤1024-char descriptions — Codex hard limit),
source↔generated sync, marketplace.json path resolution (#241 regression
guard) |
| `INSTALL.md` | CLI-first verify/repair |

Two non-obvious constraints the generator now encodes:

- the `skills` CLI matches `--skill` on **frontmatter name only**, so
the generic variant must be named `tinyfish-doctor` — and output dirs no
longer derive from the source name
- targets are opt-in per file, so Claude-specific `feedback` cannot leak
into the repo root as a generic `skills/feedback/`

`dist/harness-skills/` is deleted — nothing consumed it. `connect`
installs `use-tinyfish` from the repo root via the skills CLI, and the
CLI tarball ships no skill files.

## Verified end to end

Two live tests against the real endpoint, in opposite directions.
Neither conclusion is reachable from the CLI's output alone:

| Scenario | CLI alone says | Truth | Skill says |
|---|---|---|---|
| Healthy harness, dead CLI env key | exit 1, "fix your key" | harness
fine | harness fine ✓ |
| Stale key header on the registration | `registration: PASS` |
registration dead (401 on the wire) | broken ✓ |

The second test also surfaced a defect, fixed in a3ca8c3: several
TinyFish servers can be registered against the same endpoint at once
(plugin, CLI-written entry, account-level connector), and a healthy
sibling answering the test call was being read as proof that the
*flagged* registration works. Step 2 now counts servers first and names
which one answered.

## Upstream CLI issues found (tracked separately, not fixed here)

- registration detection reports key **presence, not validity** — a
stale key header passes as `registration: PASS` while every call 401s,
and the only repair offered (`auth login`) does not touch it
- `claude mcp get tinyfish` does not resolve `plugin:tinyfish:tinyfish`,
so `auth_mode` is permanently `unknown` for plugin installs
- doctor inspects only the server named `tinyfish` and cannot see
siblings

The design spec was removed from the repo — it was branch-scoped and
described this location as "a temporary home".

Footgun: none of this touches the CLI — the `connect --all` work is the
separate ux-labs stack (#4053–#4055).

## Review fixes (0049be5)

Three of these are things an agent following the skill would get wrong;
the `gh issue create --body` one executes user-controlled text.

| Fix | |
|---|---|
| `feedback` files via `--body-file` | the body carries free-form user
text + doctor JSON verbatim, so backticks or `$(…)` were evaluated by
the filing shell; URL fallback now says to percent-encode |
| generic `doctor`: `harnesses[]` shape | one entry per harness doctor
*knows*, not per detected one — `harness-detect.js` maps
`ALL_HARNESSES`, so an uninstalled harness returns `detected: false`,
`registered: "no"`. Old wording read as five broken registrations |
| `unattended_safe: false` is the common case | `connect <harness>` is
unsafe for every harness except Cursor, and Cursor only while the CLI
credential resolves. Read the field, don't infer from the command |
| read `schema_version` (`1`) first | the command pins `@latest`, so a
newer CLI can hand the skill a shape it doesn't know |
| `validate-skills` refuses a dirty tree | it regenerates into
`plugins/` and `skills/`; validating locally silently overwrote
uncommitted edits |
| `validate-skills` covers all of `skills/` | every skill ships through
the same `skills` CLI and faces the same 1024-char Codex limit. Surfaced
one real violation — `oss-bounty-finder` at 1127 chars, trimmed to 953 |

Plugin bumped 1.2.1 → 1.2.2: the marketplace cache is version-keyed, so
skill edits need one.


🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Zachary Lyon <zachary@lyonfamily.org>
 2026-08-17 12:59:50 -06:00
Kate Zhang 3c503e3b49 Fix skill accuracy per CodeRabbit review (#240) 
## Summary
Follow-up to #238. CodeRabbit flagged 4 accuracy issues on the
equivalent PR in tinyfish-web-agent-integrations; applying the same
fixes here since this repo's copy is still what Anthropic's Partners-tab
catalog points to.

- Fixed "no auth" wording — `.mcp.json` removes CLI/install, but first
use still triggers an OAuth sign-in and requires a TinyFish account with
credits
- Marked `agent_config.max_steps` as beta-gated (non-beta accounts get
`403 FORBIDDEN` if included)
- Documented that `if_none_match`/`if_modified_since` only work on the
fetch fast path (browser-rendered URLs may return
`conditional_unsupported`)
- Noted that search's temporal filters aren't supported with
`domain_type="research_paper"`

**Not changed:** `include_thumbnail` in the search skill — CodeRabbit
suggested removing it based on public REST docs, but it's a live
parameter on the actual `mcp__tinyfish__search` MCP tool schema, so
removing it would make the doc less accurate, not more.

## Test plan
- [x] `claude plugin validate ./plugins/tinyfish` passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-22 22:15:45 -07:00
Kate Zhang 00bf5cb7a3 Add MCP support to tinyfish plugin via new web-toolkit skill (#238) 
## Summary
- Bundle the remote TinyFish MCP server
(`https://agent.tinyfish.ai/mcp`) via `plugins/tinyfish/.mcp.json`,
loaded automatically by the plugin system — fixes the plugin for
sandboxed surfaces (Claude.ai, Desktop, Cowork) that can't install/reach
the CLI (reported by Mark Peng)
- Add a new skill, `/tinyfish:web-toolkit`, built entirely on the MCP
tools (search, fetch_content, run_web_automation,
create_browser_session, plus batch/run-management) — no CLI, no install,
no auth preflight
- `use-tinyfish` is left completely untouched — it stays the CLI-only
skill for terminal environments
- Remove the `tunneling` skill per Shuhao's request, and drop the
"tunneling" tag/mention from `marketplace.json`
- Bump plugin version to `1.1.0` (both `plugin.json` and
`marketplace.json`) so existing installs pick up the update
- Update `CHANGELOG.md`

## Test plan
- [x] `claude plugin validate ./plugins/tinyfish` passes
- [x] `claude --plugin-dir ./plugins/tinyfish` loads the MCP server;
confirmed tool names (`mcp__tinyfish__search`,
`mcp__tinyfish__fetch_content`, `mcp__tinyfish__run_web_automation`,
etc. — 18 tools total)
- [x] Confirmed both skills (`use-tinyfish`, `web-toolkit`) load side by
side and are distinguishable by description (CLI vs MCP, terminal vs
sandboxed)
- [ ] Cold-start auth test (what a brand-new, unauthenticated user sees)
— **not verified in this PR**, my local test environment already had
TinyFish MCP auth cached. Please verify the OAuth/first-run prompt
separately before the marketing push.
- [ ] Manual smoke test in Claude.ai / Desktop / Cowork to confirm
sandboxed surfaces now route to `web-toolkit` and work end-to-end

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
 2026-07-22 12:01:23 -07:00
Simantak Dabhade ea1578f0b5 Add TinyFish CLI plugin and marketplace manifest (#158) 
## Summary

- Adds a **Claude Code plugin** for the TinyFish CLI with two skills and
a marketplace manifest
- CLI-based approach (not MCP) — skills teach the agent to use
`tinyfish` commands via the Bash tool
- **Zero modifications to existing files** — all additive

## What's added

```
.claude-plugin/
  marketplace.json                          ← Makes this repo a plugin marketplace
plugins/tinyfish/
  .claude-plugin/plugin.json                ← Plugin manifest (v1.0.0)
  skills/
    use-tinyfish/SKILL.md                   ← Core CLI skill — 4-tool escalation ladder
    tunneling/SKILL.md                      ← SSH tunneling via tinyfi.sh
  CHANGELOG.md
```

## What users get

**2 skills:**
- `/tinyfish:use-tinyfish` — the complete web toolkit with 4 CLI tools
in escalation order:
  - `tinyfish search query` — web search (fastest, cheapest)
  - `tinyfish fetch content get` — clean markdown extraction from URLs
  - `tinyfish agent run` — browser automation via natural language
- `tinyfish browser session create` — raw headless browser with CDP
control
- `/tinyfish:tunneling` — expose local ports as public HTTPS URLs via
tinyfi.sh SSH tunnels

## How users install

```bash
# Add the marketplace
claude plugin marketplace add tinyfish-io/tinyfish-cookbook

# Install the plugin
claude plugin install tinyfish@tinyfish-marketplace
```

## Why CLI over MCP

Replaces the MCP-based approach from #154. The CLI route means:
- Users install `@tiny-fish/cli` once and authenticate with their own
API key
- Skills work through the Bash tool — no OAuth flows or MCP server
connections
- Consistent with every other skill in this repo that uses TinyFish

## Test plan

- [ ] `claude --plugin-dir ./plugins/tinyfish` loads both skills
- [ ] `/tinyfish:use-tinyfish` renders correctly
- [ ] `/tinyfish:tunneling` renders correctly
- [ ] `claude plugin marketplace add ./` registers the marketplace
locally
- [ ] `claude plugin install tinyfish@tinyfish-marketplace` installs
from the marketplace

---------

Co-authored-by: Simantak Dabhade <simantak@mac.local>
 2026-04-15 11:47:51 -07:00