Repository navigation
fix: update vendored skills to latest versions - #302
Merged
Merged
Conversation
pleaseai-release-bot
Bot
added
the
dependencies
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| Security | 1 high |
🟢 Metrics 0 complexity · 0 duplication
Metric Results Complexity 0 Duplication 0
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
|
🔍 Tessl Skill Review
|
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The stub design itself is maximally token-efficient — all usage detail is deferred to CLI-served content — and the commands and routing rules are tight. However, the "Why agent-browser" section is marketing-flavored ("Fast native Rust CLI, not a Node.js wrapper", "Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)") and could be trimmed, matching 'minor instances of over-explanation' rather than 'every token earns its place'. |
| actionability | █████ 5/5 | Every instruction is a copy-paste-ready command: npm i -g agent-browser && agent-browser install, agent-browser skills get core, agent-browser skills get core --full, agent-browser skills list, and seven specialized skills get commands. The common case — any browser task, load core first — is explicitly and prominently covered. |
| workflow clarity | █████ 5/5 | The sequence (install → skills get core → route to a specialized skill) is clear, with an explicit gating rule: "Before running any agent-browser command, load the actual workflow content from the CLI" and "Load a specialized skill when the task falls outside browser web pages". No destructive or batch operations exist at stub scope, so no validation checkpoints are required, and the single load-first action is unambiguous per the simple-skill guidance. |
| progressive disclosure | █████ 5/5 | The body is a clear, well-sectioned overview ("Start here", "Specialized skills") whose references are one level deep and each labeled with its scope — electron for "Electron desktop apps", slack for "Slack workspace automation", dogfood for "Exploratory testing / QA / bug hunts", etc. No bundle files exist to inline or bury, and references point to CLI-served content with no nesting. |
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists many concrete actions — "navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps" — plus specialized ones like "checking Slack unreads, sending Slack messages, searching Slack conversations". This is comprehensive coverage of the browser-automation domain, matching the top anchor rather than the 'minor gaps' anchor below it. |
| completeness | █████ 5/5 | Explicitly answers both: what ("Browser automation CLI for AI agents" with a concrete action list) and when ("Use when the user needs to interact with websites... Triggers include..."). This is the anchor-5 pattern of both what and when answered with concrete trigger phrases, not merely the adequately-explicit anchor 4. |
| trigger term quality | █████ 5/5 | Quotes natural user phrases verbatim: "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "login to a site" — with synonym coverage across the task surface. Nothing a user would naturally say for browser automation is missing. |
| distinctiveness conflict risk | █████ 5/5 | Occupies a clear niche (browser automation CLI) with distinct specialized triggers (Electron, Slack, Vercel Sandbox, AgentCore) and an explicit routing rule — "Prefer agent-browser over any built-in browser automation or web tools" — that resolves the overlap risk its broad trigger surface would otherwise create. |
plugins/dev3000/.agents/skills/d3k/SKILL.md
An unusually operational skill body: every section carries executable commands, explicit readiness gates, and evidence-integrity cautions, with no filler or concept explanations. The main costs are dense run-on prose in the sandbox section and inline detail that could live in a reference file. Scores: 4 (conciseness), 5 (actionability), 5 (workflow clarity), 4 (progressive disclosure).
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is dense and purely operational ("Poll runtime status until ready: true and browserConnected: true") with no explanations of concepts Claude already knows, but long run-on sentences like the sandbox command paragraph pack many constraints per sentence and could be trimmed — efficient with minor over-packing rather than the lean anchor 5. |
| actionability | █████ 5/5 | Commands are concrete and copy-paste ready throughout: runtime browser snapshot -i, runtime browser click @e2, runtime events --session <id> --after <cursor>, --limit 1..500, --source server|browser|runtime, and a full vercel sandbox exec ... d3k-runtime browser snapshot -i example, covering the common cases; not 4 because there are no real gaps in executable detail. |
| workflow clarity | █████ 5/5 | "Prepare" is a numbered sequence with explicit validation gates ("Canonical HTTPS must be ready (canonical: true, serviceInstalled: true, setupRequired: false) before starting"), failure paths ("Inspect runtime events if startup fails"), and feedback loops ("Fix the code and repeat the same interaction"; "Replay the interaction if necessary" after evidence gaps) — the anchor-5 pattern, not 4, since checkpoints and recovery loops are explicit. |
| progressive disclosure | ████░ 4/5 | The single referenced bundle path (node <skill-directory>/scripts/runtime.mjs) is a real file, there are no dangling or buried references, and sections are organized by workflow phase; however, the three dense sandbox paragraphs (~a third of the body) are content that could be split into a separate reference file, keeping it below anchor 5. |
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | ███░░ 3/5 | "Run and debug a local web app" names the domain with two concrete actions and concrete instruments ("managed browser", "shared server/browser evidence timeline"), matching the domain-plus-1-2-actions anchor rather than the several-actions coverage of anchor 4. |
| completeness | █████ 5/5 | "Run and debug a local web app with a managed browser and a shared server/browser evidence timeline" explicitly answers what, and "Use when asked to develop, test, or reproduce a browser issue with d3k" explicitly answers when with concrete trigger phrases — the anchor-5 pattern; it is not 4 because the when-clause is already explicit and specific. |
| trigger term quality | ████░ 4/5 | "develop, test, or reproduce a browser issue" and "d3k" are phrases a user would naturally say, giving good coverage; common synonyms like "dev server", "frontend", or "Chrome debugging" are missing, so it falls just below anchor 5. |
| distinctiveness conflict risk | ████░ 4/5 | The "shared server/browser evidence timeline" niche and the d3k name trigger make it mostly distinct, but "Run and debug a local web app" is broad enough to overlap with generic run/dev-server skills, so it is not the minimal-conflict anchor 5. |
plugins/dev3000/agent/skills/d3k/SKILL.md
The content is an unusually dense, highly actionable operations manual: nearly every line is an executable command, a concrete flag, or a d3k-specific constraint, with explicit readiness gates and error-recovery loops in the core workflows. Its weaknesses are presentational — some overloaded multi-clause sentences, a sandbox workflow whose sequence must be reconstructed from prose, and advanced sandbox/harness detail that could move to a reference file.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body assumes Claude's competence throughout — no explanations of dev servers, CDP, or HMR for their own sake — and nearly every clause carries d3k-specific operational facts. It falls short of anchor 5 only through minor trimmable redundancy ("Do not start another dev server" / "do not start another runtime or browser" repeated) and a few inline edge-case policies (e.g. unreleased-source testing, "Do not use a previously published package to test unreleased changes"). |
| actionability | █████ 5/5 | Commands are concrete and copy-paste ready with placeholders and flags throughout: "runtime portless status", "runtime events --session --after " with "--limit 1..500", "--source server|browser|runtime", "--level error", and a fully spelled-out sandbox example ("vercel sandbox exec --project --scope --workdir -- /tmp/d3k-tools/node_modules/.bin/d3k-runtime browser snapshot -i"). Expected status fields (ready: true, browserConnected: true, sessionId, cursor) are named, covering the common cases. |
| workflow clarity | ████░ 4/5 | The Prepare steps are numbered with explicit readiness gates ("canonical: true, serviceInstalled: true, setupRequired: false"; poll until "ready: true and browserConnected: true") and error-recovery paths ("Inspect runtime events if startup fails while the runtime is still alive"), and the reproduce loop includes fix-and-repeat feedback with cursor pagination and gap handling ("reset: true", "dropped"). The sandbox workflow's sequence, however, is embedded in dense prose across five long paragraphs rather than an explicit ordered flow — a minor sequencing gap that keeps it below anchor 5. |
| progressive disclosure | ████░ 4/5 | The bundle's single file, scripts/runtime.mjs, is real and clearly signaled as the entrypoint ("node /scripts/runtime.mjs"), and the body is well-organized into clear sections (Prepare, Reproduce and inspect, Lifecycle, Vercel Sandbox, CLI aliases). It does not reach anchor 5 because roughly half the document (sandbox resume, harness launching, macOS confinement) is advanced material that stays fully inline with no one-level-deep reference split, a minor organization gap. |
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | ███░░ 3/5 | "Run and debug a local web app with a managed browser and a shared server/browser evidence timeline" names the domain and two concrete actions (run, debug) plus the evidence-timeline mechanism, but does not enumerate several distinct capabilities the way the anchor-4 example does. It is above anchor 2 because the actions are concrete, not generic, but below anchor 4 because coverage is limited to two verbs. |
| completeness | ████░ 4/5 | Both parts are explicitly present: a clear what ("Run and debug a local web app with a managed browser and a shared server/browser evidence timeline") and an explicit when ("Use when asked to develop, test, or reproduce a browser issue with d3k"). The when clause could be more specific — it omits the headline "debug" and "run the dev server" scenarios — keeping it just below the fully comprehensive anchor 5. |
| trigger term quality | ████░ 4/5 | "Use when asked to develop, test, or reproduce a browser issue with d3k" supplies natural user phrases (develop, test, reproduce a browser issue) plus the tool name as a trigger. Missing a few natural terms users would say, such as "debug", "run the app", or the dev3000 alias, so it does not reach the comprehensive synonym coverage of anchor 5. |
| distinctiveness conflict risk | █████ 5/5 | The trigger is anchored to the named tool ("with d3k") and the capability (managed browser, shared evidence timeline) is a clear niche. It is more distinct than the anchor-4 example ("Works with PDF and Word document files") because users invoking this skill will name d3k or a browser-reproduction workflow, giving minimal overlap with generic web-dev skills. |
Suggestions:
- Expand the capability list to 3-4 concrete actions, e.g. "Run the dev server, drive a managed browser, replay interactions, and read a shared server/browser evidence timeline".
- Broaden the when-clause triggers to include "debug", "run the app/dev server", and the dev3000 alias so users' natural phrasings match.
plugins/emulate/.agents/skills/emulate/SKILL.md
The body is highly actionable with copy-paste-ready commands, code, and configuration, and it wastes no tokens explaining known concepts. Its main weaknesses are the oversized inline seed-config reference (~270 lines) that belongs in a one-level-deep reference file, the absence of explicit startup-verification checkpoints, and references to sibling skill files that are not part of this bundle.
Validation
⚠️ skill_md_line_count — SKILL.md is long (559 lines); consider splitting into references/ and linking⚠️ allowed_tools_field — 'allowed-tools' contains unusual tool name(s)
Full review details
Validation Checks
14/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | Mostly efficient — dense tables, commands, and code with no explanations of concepts Claude already knows — but the ~270-line inline YAML seed config covering all 14 services could be tightened to a few representative services with the full example in a reference file. It sits at 'could be tightened' rather than anchor 2's 'padded sections of unnecessary explanation', since the YAML is unknown reference material, not fluff. |
| actionability | █████ 5/5 | Fully executable throughout: 'npx emulate' quick start, a complete CLI flags table, copy-paste programmatic API ('createEmulator({ service: 'github', port: 4001 })'), a full Vitest/Jest beforeAll/afterEach/afterAll lifecycle, and a complete seed config example covering the common cases. Not 4 because there are no meaningful gaps in executability. |
| workflow clarity | ████░ 4/5 | The implicit workflow (start services → point app via env vars like GITHUB_EMULATOR_URL → write tests with reset/close lifecycle) is clearly sequenced across sections, and the test setup shows explicit state-reset checkpoints ('afterEach(() => { github.reset(); vercel.reset() })'). Falls short of 5 because there is no explicit startup-verification step (e.g., confirming a service is reachable or auth works before writing tests). |
| progressive disclosure | ███░░ 3/5 | Good section structure with headers and tables, but the bulk seed-config reference (~270 lines for 14 services) is inline when it clearly belongs in a separate reference file — matching the anchor-3 example of API reference content that should be split out. Additionally, the body cites 'skills/next/SKILL.md' and 'skills/nuxt/SKILL.md', which are not present in this bundle, and no references/ directory exists, so the split-out structure it gestures toward is not actually provided. |
Suggestions:
- Move the full 14-service seed config example to a reference file (e.g., references/seed-config.yaml) and inline only 2-3 representative services, cutting roughly 250 lines from SKILL.md and improving both conciseness and progressive disclosure.
- Add a brief verification step after startup (e.g., curl a seeded endpoint or check the installation-token endpoint) so users can confirm the emulator is reachable and auth works before writing tests.
- The body cites skills/next/SKILL.md and skills/nuxt/SKILL.md, which do not exist in this bundle — either include those files or reword the Framework Integration section to avoid dangling references.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists multiple concrete actions — "start emulated services, configure seed data, write tests against local APIs, set up CI without network access, or work with the emulate CLI or programmatic API" — covering CLI, programmatic, config, testing, and CI use cases comprehensively. It exceeds the 4 anchor ('several specific actions; minor gaps') because no meaningful capability gap remains. |
| completeness | █████ 5/5 | Explicitly answers both questions: what ("Local drop-in API emulator for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Clerk, Linear, Twilio, and other developer APIs") and when ("Use when the user needs to... Triggers include...") with concrete trigger phrases. This matches the 5 anchor exactly and goes beyond the 4 anchor's 'when could be more explicit'. |
| trigger term quality | █████ 5/5 | Explicit natural trigger phrases — "start the emulator", "emulate services", "mock API locally", "create emulator config", "test against local API", "npx emulate" — cover synonyms (emulator/mock), the CLI invocation, and a catch-all. A user needing this skill would naturally say these; coverage is comprehensive rather than merely good. |
| distinctiveness conflict risk | █████ 5/5 | A clear niche — local, stateful emulation of specific named developer APIs — with distinct triggers like "npx emulate" and "mock API locally" that no generic mocking or testing skill would claim. Minimal conflict risk; third-person voice is used throughout. |
plugins/emulate/agent/skills/emulate/SKILL.md
A highly actionable, information-dense reference that is exemplary in executable commands and code but weak in structure discipline: it is a 550-line monolith with a full multi-service config reference inlined and no bundle files to distribute detail into. The implied workflow also lacks explicit verification steps. Moving per-service configuration into reference files would address the two lowest dimensions at once.
Validation
⚠️ skill_md_line_count — SKILL.md is long (564 lines); consider splitting into references/ and linking
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | The prose itself is lean — every line is tool-specific fact (no explanations of concepts Claude already knows), and sections like the custom-emulators paragraph pack maximal detail per token. But the ~270-line inline YAML seed example exhaustively covering all 14 services far exceeds what the common single-service use case needs, so it sits at 'mostly efficient but could be tightened' rather than anchor 4. |
| actionability | █████ 5/5 | Everything is copy-paste executable: npx emulate quick start, a full CLI options table, complete createEmulator TypeScript with instance methods, a ready Vitest/Jest beforeAll/afterAll harness, and a full YAML config. Specific examples cover the common cases (GitHub, Vercel, auth fallbacks), matching the top anchor. |
| workflow clarity | ███░░ 3/5 | Section ordering (Quick Start → CLI → programmatic API → test setup → config → integration) implies a sensible flow, but the sequence is never made explicit and validation checkpoints are absent — e.g., nothing verifies a service is actually up before pointing the app at it, and the portless section only notes the proxy prerequisite incidentally. This matches 'sequence present but checkpoints missing or implicit' rather than anchor 4's 'most checkpoints present'. |
| progressive disclosure | ███░░ 3/5 | There is good section structure and the framework-integration section properly defers detail to the next/nuxt skills, but the bundle contains no reference files at all: the 270-line per-service config reference is inlined where it belongs in separate files, and the skills/next/SKILL.md / skills/nuxt/SKILL.md paths do not resolve within this bundle. This matches anchor 3's example of substantial reference content inlined despite decent structure, rather than anchor 2 which requires minimal structure. |
Suggestions:
- Split the per-service seed config examples out of the inline YAML block into one-level-deep reference files (e.g. references/config-github.md, references/config-linear.md), keeping only a minimal single-service example in SKILL.md — this would improve both conciseness and progressive disclosure.
- Add an explicit verification step after starting the emulator (e.g. curl the service URL or check the startup banner) before the 'Pointing Your App at the Emulator' section, so the setup workflow has a checkpoint.
- Fix or qualify the
skills/next/SKILL.mdandskills/nuxt/SKILL.mdreferences so they resolve from the skill's actual install location, or inline a minimal example for each framework integration.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description lists multiple concrete actions — "start emulated services, configure seed data, write tests against local APIs, set up CI without network access, or work with the emulate CLI or programmatic API" — which comprehensively covers the tool's capability surface. It stays in third person ("Local drop-in API emulator for...") with no padding or buzzwords, so it matches the top anchor rather than the 'minor gaps' anchor below it. |
| completeness | █████ 5/5 | Both halves are explicit: the "what" ("Local drop-in API emulator for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Clerk, Linear, Twilio, and other developer APIs") and the "when" ("Use when the user needs to..." followed by concrete quoted trigger phrases). This matches the anchor-5 example structure exactly and clearly exceeds anchor 4, whose 'when' is less specific. |
| trigger term quality | ████░ 4/5 | Good natural-language coverage with quoted triggers like "mock API locally", "start the emulator", and the command trigger "npx emulate", plus the named services acting as keywords. It falls short of comprehensive (anchor 5) because common synonyms such as "stub", "fake API", "offline/local development", or service-specific phrases like "mock the GitHub API" are missing. |
| distinctiveness conflict risk | ████░ 4/5 | Naming eleven specific providers plus the tool's own name and CLI command gives it a clear niche with mostly distinct triggers. It is not a 5 because generic phrases like "mock API locally" and "test against local API" could also plausibly trigger general API-mocking skills (msw, nock, wiremock), creating minor overlap risk with closely related skills. |
plugins/firebase/.agents/skills/firebase-ai-logic-basics/SKILL.md
A well-structured overview skill with an excellent, executable provisioning and App Check workflow and a sound progressive-disclosure design backed by five real reference files. Its main weakness is the Core Capabilities section, where several advertised features (text-only generation, structured output, search grounding, image generation) have no code, no guidance, and in some cases no coverage in any bundle file, plus a verbatim-duplicated model-name warning that wastes tokens.
Validation
⚠️ metadata_version — 'metadata.version' is missing⚠️ frontmatter_unknown_keys — Unknown frontmatter key(s) found; consider removing or moving to metadata
Full review details
Validation Checks
14/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is mostly lean (commands, short capability blurbs, product-specific context Claude would not know), but the 'CRITICAL: Use current model names' warning is duplicated nearly verbatim in Core Capabilities and again at the end of Initialization Code References, and the ~20-line TTS capability list ('voiceName', 'SpeechConfig', '[Audio Profile: ...]', '24 kHz 16-bit linear PCM') duplicates content in references/tts_generation.md. These are minor instances of over-explanation that could be trimmed, matching anchor 4 rather than 3 since no space is spent explaining concepts Claude already knows. |
| actionability | ███░░ 3/5 | The setup half is fully executable ('npx -y firebase-tools@latest projects:list', 'apps:list', 'init ailogic', concrete console paths 'Security > App Check > Apps > Manage debug tokens'), but the core-capabilities half is largely empty or vague: 'Text-Only Generation' is a bare header with no content, 'Enforce a specific JSON schema for the response' gives no responseSchema example, 'Search Grounding with the built in googleSearch tool' is header-only and has no implementation in any reference file, and 'Generate Images with Nano Banana' gives only a billing note. Concrete guidance exists but is incomplete with missing key details for half the advertised capabilities, matching anchor 3; not 4 because these gaps are significant rather than minor, and not 2 because provisioning and App Check sections are copy-paste ready. |
| workflow clarity | ████░ 4/5 | Setup is a clear numbered sequence with pre-action validation checkpoints ('Verify that you're running Firebase CLI commands against the intended Firebase Project' via projects:list, 'Make sure there's at least one Firebase App' via apps:list) and an explicit failure branch ('If you can't run init ailogic yourself... do NOT skip it. Tell the user to run this command'). Matches anchor 4 rather than 5 because there is no post-provisioning verification step confirming the service is enabled or that a request succeeds; not 3 because checkpoints and the error-recovery branch are present and explicit. |
| progressive disclosure | ████░ 4/5 | The body is a genuine overview with five real, one-level-deep, clearly signaled references ('read the reference for the target platform listed under Initialization Code References', per-platform reference links, and the TTS reference link), and platform code is properly delegated to them. Matches anchor 4 rather than 5 because of minor organization gaps: the trailing 'References' section duplicates links already given, the inlined TTS details overlap the TTS reference, and the empty capability sections (Text-Only Generation, Search Grounding) give no pointer to where their implementation lives; not 3 because references are clearly signaled and content is appropriately split, not buried. |
Suggestions:
- Fill the empty capability sections with a minimal code snippet or an explicit pointer to the reference that covers them: 'Text-Only Generation' is a bare header, 'Enforce a specific JSON schema for the response' needs a responseSchema example, and 'Search Grounding with the built in googleSearch tool' has no implementation in SKILL.md or in any of the five reference files.
- Remove the verbatim-duplicated 'CRITICAL: Use current model names' warning block (it appears nearly word-for-word both in Core Capabilities and at the end of Initialization Code References) and trim the inlined TTS capability bullets that duplicate references/tts_generation.md.
- Even out capability coverage across platform references: structured output (responseSchema) and Nano Banana image generation appear only in usage_patterns_web.md, so Android, iOS, and Flutter users following the skill get no implementation path for them.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description lists multiple specific concrete actions with comprehensive coverage: 'Integrates Firebase AI Logic... to call Gemini models from client code' plus 'text generation, multimodal input, chat, streaming, structured output, hybrid on-device inference, App Check protection, or switching models with Remote Config' and 'provisioning or initializing'. This matches anchor 5 ('multiple specific concrete actions; comprehensive coverage') rather than 4, since the action list spans the product's full capability surface with no notable gaps. |
| completeness | █████ 5/5 | It explicitly answers both questions: what ('Integrates Firebase AI Logic... into mobile and web apps... to call Gemini models from client code') and when ('Use when provisioning or initializing Firebase AI Logic, or adding Gemini features to an app: text generation, multimodal input, chat, streaming...'). This is an explicit 'Use when' clause with concrete trigger phrases, exactly matching anchor 5; not 4 because the 'when' is fully explicit and enumerated rather than improvable. |
| trigger term quality | █████ 5/5 | Natural keyword coverage is comprehensive and includes synonyms: 'Firebase AI Logic (formerly Vertex AI for Firebase)' captures both current and legacy product names users would say, alongside 'Gemini models', 'text generation', 'chat', 'streaming', 'structured output', 'App Check', 'Remote Config', and the platform names 'Android, iOS, Web, and Flutter'. Matches anchor 5 (comprehensive coverage including synonyms); not 4 because the key variations users actually use — the legacy Vertex AI for Firebase name and per-capability phrases — are all present. |
| distinctiveness conflict risk | ████░ 4/5 | The description occupies a clear niche (Firebase-specific Gemini integration) with distinct triggers like 'provisioning or initializing Firebase AI Logic', 'App Check protection', and 'Remote Config', but the trigger 'adding Gemini features to an app' has minor overlap risk with a hypothetical direct Gemini-API skill, and the provisioning trigger lightly overlaps a general Firebase setup skill. Matches anchor 4 ('mostly distinct; minor overlap risk with closely related skills'); not 5 because of that overlap with closely related Gemini/Firebase skills, and not 3 because the product-scoped language makes wrong-skill triggering unlikely. |
plugins/firebase/.agents/skills/firebase-app-hosting-basics/SKILL.md
A well-structured, highly actionable skill body: concrete commands, a clear decision table between Hosting and App Hosting, and clean one-level-deep references for configuration and emulation details. The main improvements are trimming the redundant opening description and adding a post-deploy validation step.
Validation
⚠️ metadata_version — 'metadata.version' is missing
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is lean and command-dense, but the "## Description" opening paragraph ("This skill enables the agent to deploy and manage modern, full-stack web applications...") duplicates the frontmatter description and is padding that could be trimmed. Otherwise it assumes Claude's competence and avoids explaining known concepts — the Hosting vs App Hosting comparison is Firebase-specific product guidance, not filler. |
| actionability | █████ 5/5 | Fully executable, copy-paste-ready guidance: a complete firebase.json apphosting block, exact npx -y firebase-tools@latest commands with concrete flags for backend creation, the full secrets pipeline (printf '%s' '<value>' | ... secrets:set then secrets:grantaccess), deploy, and rollout commands covering the common cases. |
| workflow clarity | ████░ 4/5 | The deploy-from-source flow is a clear numbered 5-step sequence with concrete commands, a pre-create checkpoint (apphosting:backends:list), and a quota fallback (switch --primary-region); the CI/CD vs local-source distinction is explicit. It falls short of anchor 5 because there is no post-deploy verification step (e.g., checking rollout/backend status) or explicit feedback loop. |
| progressive disclosure | █████ 5/5 | A ~90-line overview that keeps configuration detail in references/configuration.md and emulation detail in references/emulation.md; both files exist, are clearly signaled with markdown links, and contain no further nested references (one level deep). Content is appropriately split and easy to navigate. |
Suggestions:
- Remove the "## Description" section's opening paragraph, which restates the frontmatter description verbatim in substance; keep only the Blaze pricing requirement and upgrade URL.
- Add an explicit post-deploy verification step to the deploy-from-source workflow, e.g., check rollout status with
npx -y firebase-tools@latest apphosting:rollouts:list <backend-id>or fetch the backend URL before reporting success.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description lists multiple concrete actions — "Deploys and manages", "configuring apphosting.yaml or firebase.json apphosting blocks", "managing secrets", "setting up GitHub CI/CD", "configuring Blaze billing requirements" — comprehensively covering the skill's scope. It exceeds anchor 4 ('minor gaps in coverage') since no capability area of the skill is left unmentioned. |
| completeness | █████ 5/5 | Explicitly answers "what" ("Deploys and manages full-stack web applications (Next.js, Angular) with Server-Side Rendering (SSR) using Firebase App Hosting") and "when" ("Use when deploying Next.js/Angular apps, configuring apphosting.yaml..., managing secrets, setting up GitHub CI/CD, or configuring Blaze billing requirements") with concrete trigger phrases, plus negative triggers. |
| trigger term quality | ████░ 4/5 | Good natural-term coverage: "deploying Next.js/Angular apps", "apphosting.yaml", "firebase.json", "managing secrets", "GitHub CI/CD", "Blaze billing", plus "SSR" in both expanded and abbreviated form. A few natural phrases users would say for covered capabilities are missing (e.g., rollout, backend, emulator), which keeps it just below the comprehensive-synonym anchor 5. |
| distinctiveness conflict risk | █████ 5/5 | Clear niche (Firebase App Hosting for SSR frameworks) with explicit boundary guidance — "Don't use for classic static web hosting, Auth, Firestore, Crashlytics, or Xcode" — that disambiguates it from Firebase Hosting and other Firebase skills, minimizing conflict risk. |
plugins/firebase/agent/skills/firebase-ai-logic-basics/SKILL.md
A well-structured overview skill: the provisioning workflow is concrete and safely sequenced, critical failure modes (PERMISSION_DENIED without init ailogic, hardcoded App Check debug tokens) are prominently warned, and platform code is appropriately pushed to real one-level-deep reference files. The main weaknesses are token waste from a duplicated model-name warning and dual reference listings, plus a few capability sections that are empty headers or vague one-liners without pointers.
Validation
⚠️ metadata_version — 'metadata.version' is missing⚠️ frontmatter_unknown_keys — Unknown frontmatter key(s) found; consider removing or moving to metadata
Full review details
Validation Checks
14/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | The body is mostly lean (command-driven setup, 1-3 line capability summaries, delegated platform code), but the full CRITICAL model-name warning is duplicated verbatim ("Do NOT use any Gemini 1.x or Gemini 2.x models (such as gemini-1.5-flash...") appears twice, and the same five reference files are listed in both "Initialization Code References" and "References". The embedded deprecated-model version strings are time-sensitive content that also costs tokens. |
| actionability | ████░ 4/5 | Setup is fully executable ("npx -y firebase-tools@latest projects:list", "npx -y firebase-tools@latest init ailogic") with concrete platform delegation, and sections like multimodal give specific limits ("For files larger than 20 megabytes... store them in Cloud Storage for Firebase"). However, "### Text-Only Generation" and "### Search Grounding" are empty headers, and "Enforce a specific JSON schema for the response" is a high-level hint with no code or per-topic pointer, so gaps are more than trivial. |
| workflow clarity | ████░ 4/5 | The provisioning workflow is clearly sequenced (verify active project marked "current", check "apps:list" for a registered app, then "init ailogic") with an explicit failure path ("If you can't run init ailogic yourself... Tell the user to run this command... include it in your final summary"). Not a 5 because there are no validate-and-recover loops (e.g., what to do when no Firebase App is registered or when init fails), and the App Check steps point to external docs rather than inlining checkpoints. |
| progressive disclosure | ████░ 4/5 | All five bundle files (usage_patterns_android.md, ios_setup.md, usage_patterns_web.md, flutter_setup.md, tts_generation.md) exist, are referenced from the body, and are one level deep (they link only to external Firebase docs, not to each other). Minor gaps: the reference list is duplicated across two sections with inconsistent labels, and capability sections like structured output and search grounding do not signal which reference file holds their details. |
Suggestions:
- State the model-name deprecation warning once (e.g., in a single 'Model names' section) and drop the verbatim duplicate block at the end of the file; keep the deprecated-model list in that one place only.
- Merge the 'Initialization Code References' and 'References' sections into one navigation list, and map each capability (text generation, structured output, search grounding) to the reference file that contains its code so no section is an empty header.
- Fill or remove the empty 'Text-Only Generation' and 'Search Grounding with the built in googleSearch tool' sections — either one line naming the API call plus a pointer (as done for TTS) or delete the header entirely.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | It lists multiple concrete actions — "text generation, multimodal input, chat, streaming, structured output, hybrid on-device inference, App Check protection, or switching models with Remote Config" — plus "provisioning or initializing", comprehensively covering the body's capability set. Not 4 because coverage matches the skill's actual scope with no meaningful gaps. |
| completeness | █████ 5/5 | It explicitly answers what ("Integrates Firebase AI Logic... into mobile and web apps... to call Gemini models from client code") and when ("Use when provisioning or initializing Firebase AI Logic, or adding Gemini features to an app:...") with concrete trigger phrases, matching the top anchor exactly. |
| trigger term quality | █████ 5/5 | Natural user phrasings are well covered: "Gemini", "Firebase", "chat", "streaming", "text generation", platform names ("Android, iOS, Web, and Flutter"), and notably the synonym "formerly Vertex AI for Firebase" for users who know the old name. There are no relevant file extensions to include, and the legacy-name synonym closes the main variation gap. |
| distinctiveness conflict risk | ████░ 4/5 | The niche is clearly pinned to a named product (including its former name), so overlap risk is low, but generic feature terms like "chat", "streaming", and "text generation" could also match a plain Gemini API or general LLM-integration skill — a minor overlap with closely related skills rather than minimal. Not 5 because those generic triggers are shared with adjacent skills; not 3 because the Firebase-specific product framing dominates. |
plugins/firebase/agent/skills/firebase-app-hosting-basics/SKILL.md
A well-structured, highly actionable skill body: executable commands throughout, a clear decision guide (Hosting vs App Hosting), and properly delegated detail in real one-level-deep reference files. The only minor deductions are a redundant Description section and the absence of post-deploy verification steps.
Validation
⚠️ metadata_version — 'metadata.version' is missing
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is lean and product-specific (Blaze plan prerequisite, backend quota workaround, exact CLI invocations), but the "## Description" section restates the frontmatter description almost verbatim, which is trimmable redundancy. Anchor 5 would require every token to earn its place with no such repetition. |
| actionability | █████ 5/5 | Fully executable, copy-paste-ready guidance: a complete firebase.json apphosting block, backend creation with flags, secrets set/grant pipelines via printf, deploy and rollouts:create commands, plus a --help discovery pattern for remaining flags. Common cases are covered end to end. |
| workflow clarity | ████░ 4/5 | The deploy-from-source flow is a clear 5-step numbered sequence with a conditional checkpoint ("Create the backend if it does not exist (apphosting:backends:list… switch --primary-region… if a region hits its 10-backend quota)") and a guard against misusing rollouts:create. It falls short of anchor 5 only because there is no post-deploy verification or error-recovery loop; deploy is not destructive, so the cap-at-3 rule does not apply. |
| progressive disclosure | █████ 5/5 | Verified against the actual bundle: references/configuration.md and references/emulation.md both exist, are substantive, one level deep, and clearly signaled inline ("see Configuration", "See Emulation"). The overview stays in SKILL.md with detail appropriately split out. |
Suggestions:
- Remove or shrink the '## Description' section, which duplicates the frontmatter description verbatim, to reclaim tokens.
- Add a brief post-deploy verification step (e.g., checking rollout/backend status with apphosting:backends:get or apphosting:rollouts:list) to close the workflow with a validation checkpoint.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists multiple concrete actions covering the full workflow — "deploying Next.js/Angular apps, configuring apphosting.yaml or firebase.json apphosting blocks, managing secrets, setting up GitHub CI/CD, or configuring Blaze billing requirements" — with comprehensive coverage matching the top anchor. |
| completeness | █████ 5/5 | Explicitly answers both what ("Deploys and manages full-stack web applications… using Firebase App Hosting") and when ("Use when deploying… configuring… managing… setting up…") with concrete trigger phrases, plus negative triggers ("Don't use for classic static web hosting, Auth, Firestore, Crashlytics, or Xcode"). |
| trigger term quality | █████ 5/5 | Comprehensive natural-term coverage including concrete file names ("apphosting.yaml", "firebase.json"), framework names ("Next.js, Angular"), and feature keywords users would say ("SSR", "secrets", "GitHub CI/CD", "Blaze billing"). |
| distinctiveness conflict risk | █████ 5/5 | Clear niche (Firebase App Hosting, explicitly distinguished from "classic static web hosting") with an explicit exclusion list that minimizes overlap with other Firebase skills. |
plugins/mastra/.agents/skills/mastra/SKILL.md
A well-structured router skill: an accurate routing table with verified files and anchors, copy-paste-ready commands, and verification steps woven into its workflows. The main weaknesses are repetition of the verify-first doctrine across overlapping sections and minor validation softness in the workflow steps.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is mostly terse pointer tables and directives that assume competence ('Agent: Use for open-ended tasks that make decisions and use tools'), but the verify-first doctrine is repeated across four sections ('Never rely on memory', 'Never write code without checking current docs first', 'Type errors often mean your knowledge is outdated', 'Always verify before writing code') and the embedded/remote docs priority is explained twice. Not 5: those repetitions could be consolidated; not 3: it never teaches concepts Claude already knows. |
| actionability | █████ 5/5 | Copy-paste-ready commands cover the body's common cases: 'ls node_modules/@mastra/', 'npm run dev' plus 'http://localhost:4111', 'npx skills add mastra-ai/skills --skill mastra-factory', 'scripts/provider-registry.mjs', the '"provider/model-name"' format, and '--schema', alongside concrete decision rules ('If packages exist: Use embedded docs first'). Not 4: the gaps are negligible — even lookup paths like 'node_modules/@mastra/*/dist/docs/' are specified. |
| workflow clarity | ████░ 4/5 | Clear numbered sequences with embedded verification ('Check installed packages and versions, then verify the capability's APIs, configuration, and limits'; 'verify compatibility before adopting newer features') and an error-recovery loop ('Check common-errors.md' then 'Verify current API in embedded docs'). Not 5: 'Priority order for writing code' and 'Development workflow' overlap without stating their relationship, the final step is soft ('Test with the project scripts or Studio when available'), and 'confirm that the installed CLI exposes the command' gives no concrete check; not 3: most checkpoints and a feedback loop are present. |
| progressive disclosure | █████ 5/5 | The 'User Question | First Check | How To' routing table maps 16 questions to reference files; all 10 referenced files exist and every deep-link anchor (#aggregate-traces, #query-spans, #aggregate-spans, #discover-native-capabilities-first) resolves to a real heading, with references cross-linking only to siblings. The ~145-line body stays a genuine overview with detail pushed to one-level-deep references. Not 4: navigation is easy, structure is clean, and the split is appropriate. |
Suggestions:
- Consolidate the verify-first doctrine, which currently appears in four places ('Critical: Do not trust internal knowledge', 'Priority order for writing code', 'When you see errors', 'Development workflow'), into one canonical section that the others reference.
- Merge or explicitly relate the overlapping 'Priority order for writing code' and 'Development workflow' sections — both describe the embedded-docs/source/remote-docs decision without stating which governs.
- Make the soft checkpoints concrete: name the test step ('Test with the project scripts or Studio when available') and specify how to confirm CLI command availability (e.g., 'mastra api trace query --help').
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists many concrete actions — 'building agents, workflows, tools, memory, workspaces, and storage', 'logging, tracing, metrics/cost estimates, dataset experiments', 'TypeScript setup, common errors, migrations', 'inspect or call resources on local, Mastra platform, or remote servers', 'report verified bugs and concrete documentation defects' — with comprehensive coverage of the skill's actual scope. Not 4: coverage has no gaps relative to the body's topics. |
| completeness | █████ 5/5 | Explicitly answers 'what' ('Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs') and 'when' via a concrete 'Use for native capability discovery, logging, tracing, ...' trigger list. Not 4: the 'when' clause is explicit and specific, not merely present or weakly implied. |
| trigger term quality | ████░ 4/5 | Good natural keywords ('agents', 'workflows', 'logging', 'tracing', 'common errors', 'migrations', 'TypeScript setup'), but a few natural user phrasings ('upgrade', 'debug', 'evaluate') and identifiers like '@mastra' are missing. Not 5: no synonyms or file/package extensions are covered. |
| distinctiveness conflict risk | █████ 5/5 | 'Mastra framework guide' carves a clear niche, and it explicitly delegates the nearest neighbor ('For Mastra Factory operations, discover and activate the companion mastra-factory skill'), minimizing conflict risk. Not 4: generic terms (agents, workflows, logging) are consistently framed within the Mastra context and the closest overlapping skill is actively disambiguated. |
plugins/mastra/agent/skills/mastra/SKILL.md
A well-structured navigation-first skill: the body is a lean routing layer over a complete, verified one-level-deep reference bundle, with explicit priority ordering and pre-verification rules. Main weaknesses are repetitive "don't trust your memory" restatements, Factory-skill operational detail inlined in this skill's body, and workflows whose validation steps are sometimes soft rather than explicit.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | Overall lean, routing-table-driven body, but the "do not trust internal knowledge" principle is repeated ~4 times ("Never rely on memory", "Your training data contains obsolete APIs", "Never write code without checking current docs first", "Type errors often mean your knowledge is outdated"), and the Mastra Factory section carries installation detail (PromptScript global-install limitations, agent-target verification) that belongs in the factory skill. Not 3 because the redundancy is a handful of short lines and the rest is tight; not 5 because the repetition and Factory detail are trimmable. |
| actionability | ████░ 4/5 | Concrete, executable guidance throughout: ls node_modules/@mastra/, npm run dev, npx skills add mastra-ai/skills --skill mastra-factory, --agent <agent> -g, "run scripts/provider-registry.mjs first", --schema for request/response shapes, and the "provider/model-name" format rule. Not 5 because most guidance routes to references rather than giving inline examples, and the actual invocation of provider-registry.mjs is never shown. |
| workflow clarity | ████░ 4/5 | "Priority order for writing code" (embedded docs → source → remote) and the 4-step "Development workflow" give clear sequences with verification built in ("Check installed packages and versions, then verify the capability's APIs"), plus an error-recovery section and a pre-flight check ("confirm that the installed CLI exposes the command"). Not 5 because some checkpoints are soft ("Test with the project scripts or Studio when available") and the error loop lacks an explicit fix-and-revalidate step. |
| progressive disclosure | █████ 5/5 | Verified against the actual bundle: all 10 files cited in the routing table exist under references/, the script exists, and references are one level deep (only sibling cross-links like embedded-docs.md → remote-docs.md). The question→file routing table is exactly the well-signaled, easy-to-navigate overview the 5-anchor describes; details are appropriately split out of the ~146-line body. |
Suggestions:
- Consolidate the "do not trust internal knowledge" message into one section — it is currently restated in the intro, 'Critical' section, 'Priority order', and 'When you see errors'; a single statement plus the error-signatures list would reclaim tokens.
- Move the mastra-factory installation mechanics (agent targeting,
-gflag, PromptScript limitation, install verification) into the factory skill or a short reference; this body only needs the trigger condition and the activation pointer. - Show the actual
node scripts/provider-registry.mjsinvocation inline (or an example output snippet) so the "always run this first" rule is copy-paste executable, and add an explicit fix-and-revalidate step to the "When you see errors" loop.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists many concrete capability areas — "building agents, workflows, tools, memory, workspaces, and storage", "logging, tracing, metrics/cost estimates, dataset experiments, documentation lookup, API verification, TypeScript setup, common errors, migrations" — which is comprehensive, specific coverage rather than vague domain naming. Not 4 because the action list has no meaningful coverage gaps for the framework's surface. |
| completeness | █████ 5/5 | Explicitly answers "what" ("Comprehensive Mastra framework guide for building agents, workflows, tools, memory, workspaces, and storage with current APIs") and "when" via an explicit "Use for ..." clause enumerating concrete triggers. Not 4 because the when-clause is explicit and trigger-specific rather than merely present. |
| trigger term quality | ████░ 4/5 | Good natural-keyword coverage: "agents", "workflows", "tracing", "metrics", "common errors", "migrations", "TypeScript setup", "inspect or call resources". Not 5 because a few of natural phrases users would say are missing (e.g., Mastra Studio/playground, dev server, MCP, "create a Mastra app"), and terms are capability nouns rather than varied synonyms. |
| distinctiveness conflict risk | █████ 5/5 | Anchored to a distinct niche (the Mastra framework), and it actively de-conflicts its nearest sibling: "For Mastra Factory operations, discover and activate the companion mastra-factory skill." Not 4 because the sibling-skill boundary is explicitly routed, leaving minimal overlap risk. |
plugins/orpc/.agents/skills/orpc-openapi/SKILL.md
An excellent reference-style skill body: dense with version-specific, non-inferable API detail, fully executable examples for every major task, and a clean structure that defers depth to named docs pages. The only soft spot is that verification guidance is localized to one section rather than framed as a final wiring check for all paths.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | █████ 5/5 | The body assumes competence and delivers only non-guessable v2 facts: 'prefix and tags concatenate, method/path/successStatus last-wins', 'It cannot represent empty objects or arrays, root-level arrays...', 'JsonifiedClient exists because OpenAPI serialization is one-way: a Date returns as a string'. There is no filler or explanation of known concepts; the version references are descriptive and paired with a trust-the-fetched-page rule rather than date-conditional instructions, so this fits 'every token earns its place' rather than anchor 4's 'minor instances of over-explanation'. |
| actionability | █████ 5/5 | Five complete, copy-paste-ready TypeScript examples with real imports cover the common cases — route metadata, the .route extension, OpenAPIHandler with Smart Coercion in a fetch handler, an OpenAPILink client, and the generator plus reference plugin — supplemented by exact option names (paramsStyles, requestBodyHint, errorStatusMap). This matches 'fully executable; specific examples cover the common cases'. |
| workflow clarity | ████░ 4/5 | Sections progress in build order (Routing → Input/output mapping → Serving → Calling → Spec/docs → Contract-first) and include an explicit verification step ('request /spec.json under the handler prefix and one routed endpoint, and confirm the method, path, and status you configured') plus a fetch-docs feedback loop for stale knowledge. It sits at anchor 4 rather than 5 because validation is scoped to the docs wiring section instead of a global end-of-work checklist, leaving most checkpoints implicit for the serving/client paths. |
| progressive disclosure | █████ 5/5 | With no bundle files, the skill uses one-level-deep external references, clearly signaled: the 'Full documentation' section gives the llms.txt index, per-page .md fetch pattern, and a topic→page list ('OpenAPI: openapi/routing, ... ; Plugins: plugins/smart-coercion, plugins/openapi-reference'), and out-of-scope work is routed to the orpc and orpc-contract skills by name. Navigation is easy and the split is appropriate, matching the clear-overview anchor rather than anchor 4's 'minor organization gaps'. |
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description enumerates the skill's full capability surface with concrete API names — 'defining REST-style routes on oRPC procedures (openapi() metadata or .route with method, path, successStatus)', 'serving them with OpenAPIHandler alongside RPCHandler', 'coercing query and path strings with Smart Coercion', 'calling an OpenAPI-shaped API with OpenAPILink', 'generating an OpenAPI 3.2 (or 3.1, 3.0) document with OpenAPIGenerator', 'serving Scalar or Swagger docs'. This matches the anchor 'multiple specific concrete actions; comprehensive coverage' rather than anchor 4, which expects minor gaps — routing, serving, coercion, client calls, spec generation, and docs UI are all named. |
| completeness | █████ 5/5 | Both questions are answered explicitly: 'what' via 'Expose an oRPC router as a spec-compliant OpenAPI HTTP API' and the capability list, and 'when' via the explicit 'Use when a project depends on @orpc/openapi, or for defining REST-style routes...' clause with concrete trigger phrases. It additionally covers when NOT to use it, exceeding the anchor-5 example's structure; it is clearly not anchor 4, where the 'when' is only loosely specified. |
| trigger term quality | █████ 5/5 | Natural terms a user in this niche would say are comprehensively covered: 'OpenAPI', 'REST-style routes', 'HTTP API', 'spec', 'Swagger', 'Scalar', '@orpc/openapi', plus tool names (OpenAPIHandler, OpenAPILink, OpenAPIGenerator, Smart Coercion) and version synonyms ('OpenAPI 3.2 (or 3.1, 3.0)'). Nothing a user would plausibly say when needing this skill is missing, matching the comprehensive-coverage anchor rather than anchor 4's 'a few natural terms missing'. |
| distinctiveness conflict risk | █████ 5/5 | The niche is unambiguous (oRPC + OpenAPI exposure) and it preempts conflicts by routing contract-first work to 'the orpc-contract skill' and 'plain RPC serving, core builder, middleware, or client work' to 'the orpc skill instead'. Distinct package and class names give it triggers no sibling skill would match — a clear anchor-5 fit. |
plugins/orpc/agent/skills/orpc-openapi/SKILL.md
A dense, expert-aimed reference that wastes no tokens: every section adds oRPC v2 specifics Claude cannot know from training, with complete executable TypeScript examples and an explicit wiring-verification step. The workflow is topical rather than procedural, with only one validation checkpoint and no error-recovery loop, and some fine-grained reference detail is inlined in the single file instead of being pushed to the referenced docs pages.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | █████ 5/5 | Every section carries non-inferable v2 specifics — "prefix and tags concatenate, method/path/successStatus last-wins", "fetch openapi/bracket-notation before designing schemas for nested query input; its limits are not guessable", "Skip it when you already coerce in the schema or performance is critical" — with zero filler and no explanation of what OpenAPI or REST is. This matches the 'lean and efficient; every token earns its place' anchor; the v1/v2 note is essential version targeting, not date-sensitive padding, so it does not drop to 4. |
| actionability | █████ 5/5 | Five complete, copy-paste-ready TypeScript blocks (openapi meta, the '.route' extension with its side-effect import, OpenAPIHandler with a fetch handler and 404 fallback, OpenAPILink with typed client, OpenAPIGenerator plus OpenAPIReferenceHandlerPlugin) cover the common cases, plus a concrete verification instruction: "request /spec.json under the handler prefix and one routed endpoint, and confirm the method, path, and status you configured". Fully executable — matches the 5 anchor, not 4, since there are no gaps in the core flows. |
| workflow clarity | ████░ 4/5 | Sections follow a coherent build order (routing → input/output mapping → serving → calling → spec/docs → contract-first) and include one explicit checkpoint ("Verify the wiring before declaring success"), matching 'clear sequence with most checkpoints present; minor validation gaps'. Not 5 because there is no error-recovery feedback loop or checklist for when verification fails; not 3 because the sequence and an explicit checkpoint are present and no destructive/batch operations apply. |
| progressive disclosure | ████░ 4/5 | No bundle files exist, and the single file is well-sectioned with a 'Full documentation' section that clearly signals where deeper detail lives ("Pages to fetch when you need details beyond this skill", the llms.txt index, and "Append .md to any docs URL") — references are one level deep and well-signaled. It sits at 4 rather than 5 because fine-grained enumerations (paramsStyles/queryStyles variants, the bracket-notation edge-case list) are inlined rather than deferred to the referenced docs pages. |
Suggestions:
- Add an error-recovery branch to the verification step (e.g., what to re-check when /spec.json or a routed endpoint returns 404 — prefix mounting, the '@orpc/openapi/extensions/route' side-effect import, or missing openapi metadata) so the workflow has a feedback loop.
- Defer the paramsStyles/queryStyles style enumerations and the bracket-notation edge-case list to the referenced docs pages (openapi/serializer, openapi/bracket-notation) to keep SKILL.md a leaner overview.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | It lists multiple concrete actions with named APIs: "defining REST-style routes on oRPC procedures (openapi() metadata or .route with method, path, successStatus)", "serving them with OpenAPIHandler alongside RPCHandler", "coercing query and path strings with Smart Coercion", "calling an OpenAPI-shaped API with OpenAPILink", "generating an OpenAPI 3.2 ... document with OpenAPIGenerator", and "serving Scalar or Swagger docs with the OpenAPI Reference plugin". This is comprehensive coverage of the skill's capabilities — the 5 anchor — not 4, since there are no coverage gaps, and it stays in third person. |
| completeness | █████ 5/5 | The what is explicit ("Expose an oRPC router as a spec-compliant OpenAPI HTTP API") and the when is an enumerated, concrete trigger list ("Use when a project depends on @orpc/openapi, or for defining REST-style routes..., serving them with OpenAPIHandler..., coercing..., calling..., generating..., or serving Scalar or Swagger docs"). Clearly answers both with concrete trigger phrases — the 5 anchor; not 4 because the 'when' is already fully explicit rather than 'could be more specific'. |
| trigger term quality | █████ 5/5 | Natural user phrasings are covered with synonyms and variants: "OpenAPI", "REST-style routes", "HTTP API", "Swagger"/"Scalar", "query and path strings", the package name "@orpc/openapi", and version variants "OpenAPI 3.2 (or 3.1, 3.0)". A user asking about any of these needs this skill, matching the 'comprehensive coverage of natural terms including synonyms' anchor; not 4 because both layperson terms and the exact library identifiers users would type are present. |
| distinctiveness conflict risk | █████ 5/5 | It carves out a clear niche and actively routes around conflicts: "For contract-first work (defining contracts with oc, implementing them with implement, or generating a contract from an existing OpenAPI spec), use the orpc-contract skill; for plain RPC serving, core builder, middleware, or client work with no REST exposure, use the orpc skill instead." With the highly specific @orpc/openapi domain and explicit sibling disambiguation, conflict risk is minimal — the 5 anchor; not 4 because the overlap boundaries are stated, not merely implied. |
plugins/portless/.agents/skills/portless/SKILL.md
Highly actionable and well-organized reference for a CLI tool, with strong troubleshooting and validation guidance, but it is a monolithic 500+ line file with no progressive disclosure and notable duplication between the 'How It Works' and 'Troubleshooting' sections. Splitting reference material into linked files and deduplicating would materially improve it.
Validation
⚠️ skill_md_line_count — SKILL.md is long (517 lines); consider splitting into references/ and linking
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | The body is tool-specific rather than explaining known concepts, but it could be tightened: the framework PORT-injection rules appear nearly verbatim in both 'How It Works' (line 182) and 'Troubleshooting' (line 417), proxy auto-start is restated four times, and the unprivileged-mode paragraph (line 172) is a ~200-word wall. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' better than 4's 'minor instances of over-explanation', given the scale of the duplication. |
| actionability | █████ 5/5 | Guidance is copy-paste ready throughout: install commands, quick start, portless.json/package.json config examples, a full CLI command table, an env-var table, machine-readable error JSON with field names, and a concrete vite.config.ts fix. Specific examples cover the common cases (Next.js, monorepo, turborepo, worktrees, sharing). |
| workflow clarity | ████░ 4/5 | Quick Start gives a clear install→run→URL sequence, 'portless doctor' is designated as the first validation step, 'portless list' verifies routes, and Troubleshooting follows symptom→error code (404/421/502/508)→fix with recovery loops (e.g. proxy loop → changeOrigin). Not 5 because the main integration flows lack an explicit post-step verification (e.g. confirm the URL responds after trust/first run); not 3 since checkpoints like doctor/list and error-code fixes are explicit. |
| progressive disclosure | ███░░ 3/5 | The bundle contains no reference files at all; a 517-line SKILL.md inlines the full CLI reference, env-var table, sharing guides (Tailscale/ngrok/Cloudflare), and OS service details — content that clearly belongs in separate linked files. Well-organized section headers keep it above the 2 anchor's 'minimal structure', but it sits squarely on 'content that should be separate is inline'. |
Suggestions:
- Move the CLI reference table, env-var table, sharing options (Tailscale/ngrok/Cloudflare), and OS startup service sections into one-level-deep reference files (e.g. references/cli.md, references/sharing.md) linked from a leaner SKILL.md overview.
- Deduplicate the framework PORT-injection rules, which appear nearly verbatim in both 'How It Works' and 'Troubleshooting > Framework not respecting PORT'; state them once and cross-reference.
- Break dense paragraph blocks (the unprivileged-mode and error-response paragraphs) into scannable bullets or short subsections to reduce token cost per lookup.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description lists multiple concrete actions — 'Set up and use portless', 'configuring dev server names', 'setting up the local proxy', 'troubleshooting port/proxy issues' — with a literal example URL (https://myapp.localhost instead of http://localhost:3000), covering setup, configuration, proxy, domains, and troubleshooting comprehensively. It is not score 4 because coverage has no minor gaps across the tool's use cases, and not below 5 since every action is concrete rather than generic. |
| completeness | █████ 5/5 | It clearly answers 'what' (named local dev server URLs, with a concrete example) and 'when' via an explicit 'Use when...' clause listing five concrete trigger phrases (integrating, configuring dev server names, setting up the local proxy, .localhost domains, troubleshooting). This matches the 5 anchor exactly; score 4 would require the 'when' clause to be less explicit or specific. |
| trigger term quality | ████░ 4/5 | Natural phrases a user would say are present: 'local dev server URLs', '.localhost domains', 'port/proxy issues', and the literal 'localhost:3000'. It falls short of the 5 anchor because common variations like 'port conflict', 'port numbers', 'EADDRINUSE', or 'named URLs' are missing, but it is above 3 since several natural terms beyond the domain name are covered. |
| distinctiveness conflict risk | █████ 5/5 | It names the specific tool 'portless' and anchors on distinct triggers (.localhost domains, local proxy, port/proxy issues for local dev servers), giving it a clear niche with minimal overlap risk against generic web-dev or networking skills. No neighboring anchor fits better. |
plugins/portless/agent/skills/portless/SKILL.md
Highly actionable, well-sectioned reference with excellent concrete commands and error-recovery guidance. Its weaknesses are token efficiency (verbatim duplication of the framework-injection rules and repeated auto-start/cert-trust notes) and the absence of any progressive disclosure — the full CLI reference, sharing, and troubleshooting material should be split into bundled reference files.
Validation
⚠️ skill_md_line_count — SKILL.md is long (520 lines); consider splitting into references/ and linking
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | Almost all content is novel tool-specific fact rather than explanation of known concepts, but there is noticeable duplication: the framework PORT-injection rules appear nearly verbatim in both "How It Works" (line 185) and "Troubleshooting" (line 420), the proxy auto-start note repeats four times (lines 54, 129, 169, 404), and cert-trust and sudo-fallback details recur across multiple sections. Fits anchor 3 (mostly efficient, could be tightened) better than 4, where over-explanation would be only minor. |
| actionability | █████ 5/5 | Fully executable throughout: copy-paste bash commands, complete config JSON snippets for every integration pattern, a full env-var and CLI-reference table, and even the exact JSON error-body shape to parse instead of scraping HTML. Covers the common cases comprehensively. |
| workflow clarity | ████░ 4/5 | Quick Start gives a clear install→run→URL sequence, portless doctor is an explicit first-line validation step, and Troubleshooting provides error-to-fix feedback loops (502, 508 loop, cert warnings, Safari DNS). Not a 5 because the main flow lacks an explicit post-start verification checkpoint (e.g. portless list after first run). |
| progressive disclosure | ███░░ 3/5 | The bundle has no reference files at all and the body references none — everything is inlined in a ~520-line SKILL.md, including a 46-row CLI table, sharing/tunnel sections, and a long troubleshooting guide that clearly belong in separate reference files. Internal section structure is good (better than anchor 2's "minimal structure"), but content that should be separate is entirely inline, matching anchor 3. |
Suggestions:
- Deduplicate the framework PORT-injection rules: state them once (either in "How It Works" or "Troubleshooting") and cross-reference the other section instead of repeating the ~150-word explanation verbatim; same for the proxy auto-start note and cert-trust instructions.
- Split the 46-row CLI Reference table, the Tailscale/ngrok/Cloudflare sharing sections, and the Troubleshooting guide into references/ files (e.g. references/cli.md, references/sharing.md, references/troubleshooting.md), keeping SKILL.md as a concise overview with clearly signaled one-level-deep pointers.
- Add an explicit verification step to Quick Start (e.g. run
portless listafter starting an app to confirm the route and URL) to close the workflow-clarity validation gap.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | ████░ 4/5 | Lists several concrete actions ("Set up and use portless", "configuring dev server names", "setting up the local proxy", "troubleshooting port/proxy issues") with a literal example URL. Falls short of anchor 5 because some verbs are generic ("working with .localhost domains") and coverage gaps exist (no mention of sharing, worktrees, or monorepo support). |
| completeness | █████ 5/5 | Explicitly answers both: what it does ("named local dev server URLs" with an example) and when to use it ("Use when integrating portless into a project, configuring dev server names, setting up the local proxy, working with .localhost domains, or troubleshooting port/proxy issues") — five concrete trigger clauses. |
| trigger term quality | ████░ 4/5 | Good natural keyword coverage: "dev server", "localhost", "port", "proxy", ".localhost domains", plus concrete URLs like "https://myapp.localhost" and "http://localhost:3000" that users would literally paste. A few natural terms are missing (e.g. "port conflict", "port already in use", "EADDRINUSE"). |
| distinctiveness conflict risk | █████ 5/5 | Names a specific tool (portless) with distinct, niche triggers (.localhost domains, local dev proxy); no other plausible skill would fire on these phrases, so conflict risk is minimal. |
plugins/react/.agents/skills/vercel-react-view-transitions/SKILL.md
The body is a strong, actionability-first reference: executable JSX for every pattern, non-obvious gotchas (placement rule, default="none" semantics, back-button type behavior, nested VT limitation) that Claude could not infer, and clean one-level-deep delegation to five real reference files. The small deductions are for redundant restatement in the opening sections, inline version numbers, validation steps that live only in the referenced workflow, and one dead AGENTS.md pointer.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is dense and assumes competence — no explanation of what React or CSS transitions are, every code block minimal — but a few spots could be trimmed: the "When to Animate" section states the implementation-order rule three ways ("in this order", "This is an implementation order, not a 'pick one' list", "Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it"), the lateral-navigation guidance is repeated in both the style table and the paragraph below it, and inline version numbers ("19.3 or newer", "Chromium 125+... Firefox 144+, Safari 18.2+") are time-sensitive. This fits anchor 4 (efficient, minor over-explanation) better than 5, where every token would earn its place. |
| actionability | █████ 5/5 | Code is copy-paste-ready JSX throughout — imports, prop usage, a works/broken contrast for the placement rule, type-keyed object maps, a reusable DirectionalTransition wrapper, shared-element pairing, list reorder, force re-enter, and two Suspense reveal variants — covering the common cases, with concrete CSS delegated to the existing css-recipes.md. This matches the fully-executable anchor-5 example; nothing is pseudocode. |
| workflow clarity | ████░ 4/5 | There is a clear, explicit sequence — a priority-ordered pattern table (1–5), a directive to "follow references/implementation.md step by step. Start with the audit — do not skip it", and a symptom-driven troubleshooting reference for error recovery — and the referenced workflow ends in "Step 7: Verify Each Navigation Path". However, the validation checkpoints live in the reference files rather than the body itself, which fits anchor 4 ('most checkpoints present; minor validation gaps') rather than anchor 5's inline explicit validation steps and feedback loops. |
| progressive disclosure | ████░ 4/5 | Structure is good: five one-level-deep reference files, each linked at its point of use and summarized in a Reference Files section, with verified anchors (patterns.md#layout-displacement-morph, css-recipes.md#reduced-motion) and decision-critical content kept inline. The gap is the dangling "Full Compiled Document: AGENTS.md" pointer — AGENTS.md does not exist in the bundle — which is a minor navigation dead-end that fits anchor 4's 'minor organization gaps' rather than anchor 5's 'easy navigation'. |
Suggestions:
- Collapse the triple-stated implementation-order rule in "When to Animate" to a single sentence, and drop the paragraph restating the lateral-navigation table row, to tighten conciseness toward anchor 5.
- Remove or qualify the "Full Compiled Document: AGENTS.md" pointer, or ship the AGENTS.md file, so every reference in the body resolves within the bundle.
- Add a brief inline validation checkpoint in the Implementation Workflow section (e.g., 'verify each navigation path after wiring, per implementation.md Step 7') so error-recovery guidance is visible without opening the reference.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists multiple specific concrete actions — "add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js" — and names the exact API surface ("<ViewTransition> component, addTransitionType, and CSS view transition pseudo-elements"). Coverage spans the component's full use-case space, matching the comprehensive anchor rather than the 'minor gaps' anchor 4. |
| completeness | █████ 5/5 | Explicitly answers 'what' ("Guide for implementing smooth, native-feeling animations using React's View Transition API...") and 'when' with two concrete trigger clauses ("Use this skill whenever the user wants to..." and "Also use when the user mentions..."). This mirrors the anchor-5 good example's structure exactly; a 4 would require the 'when' to be less explicit or specific, which it is not. |
| trigger term quality | █████ 5/5 | Covers natural phrases users would say ("page transitions", "animate route changes", "animate list reorder", "animating between UI states") alongside exact API tokens a user might paste ("startViewTransition", "ViewTransition", "transition types"), and includes the disambiguating variation "without third-party animation libraries". This comprehensively covers both lay and technical synonyms, matching the anchor-5 pattern of 'natural terms including synonyms'. |
| distinctiveness conflict risk | █████ 5/5 | The niche is clear and React-specific, with distinct triggers — component/API names (<ViewTransition>, startViewTransition, addTransitionType) and the qualifier "in React without third-party animation libraries" that separates it from generic CSS-animation skills like framer-motion. Only a trace of overlap risk remains for non-React view-transition requests, which the consistent "React" anchoring largely forecloses. |
plugins/react/agent/skills/vercel-react-view-transitions/SKILL.md
A well-engineered body: it inlines only core concepts and common patterns, offloads depth to five real, well-signaled reference files, and backs nearly every instruction with executable code and hard-won gotchas. The deductions are a dangling pointer to a nonexistent AGENTS.md, a couple of redundant passages plus time-sensitive version numbers, and the absence of any explicit validation checkpoint in the body's own workflow.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is dense with non-obvious, API-specific knowledge (placement rules, trigger semantics, nested-VT limitations) and assumes Claude's competence — no basic-concept explanations — but is not quite 'every token earns its place': the three-sentence restatement after the priority table ("This is an implementation order, not a 'pick one' list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.") says one thing three ways, the 'Choosing Animation Style' table and the paragraph below it partially repeat the lateral-navigation guidance, and the Availability section carries time-sensitive version numbers ("React 19.3", "Chromium 125+", "Firefox 144+", "Safari 18.2+") outside any old-patterns/deprecated section, which the guidelines say should penalize conciseness. This lands between anchors 4 and 5, clearly above the midpoint — hence 4. |
| actionability | █████ 5/5 | Every pattern ships executable, copy-paste-ready JSX with exact prop values ("<ViewTransition default="none" enter={{ 'nav-forward': 'slide-from-right', ... }} default: 'none' }>", list-reorder keyed map, nested shared-element composition, Suspense fallback-to-content), plus a concrete TypeScript requirement ("ViewTransitionClassPerType requires a default key") and correct/incorrect placement examples. The custom CSS classes referenced are backed by the real css-recipes.md, so examples are fully executable end-to-end — a direct match for anchor 5. |
| workflow clarity | ████░ 4/5 | There is a clear, explicitly ordered implementation sequence (the priority table with "Implement all applicable patterns from this list, in this order") plus a hard directive to follow the step-by-step workflow file ("follow references/implementation.md step by step. Start with the audit — do not skip it") and a symptom-driven troubleshooting reference. However, the body itself contains no explicit validation checkpoints (e.g., verify animations fire in a supported browser or confirm graceful degradation), which keeps it at anchor 4 ('clear sequence with most checkpoints present; minor validation gaps') rather than 5; it does not fall to 3 because the sequence is strong and the skill involves no destructive or batch operations requiring the validation cap. |
| progressive disclosure | ████░ 4/5 | Structure against the actual bundle is strong: all five referenced files (implementation.md, patterns.md, troubleshooting.md, css-recipes.md, nextjs.md) exist, references are one level deep with verified deep-link anchors (patterns.md#layout-displacement-morph, css-recipes.md#reduced-motion), and a Reference Files index section signals each file's purpose. The defect is that the 'Full Compiled Document' section points to AGENTS.md, which does not exist in the bundle — a dangling reference that breaks navigation for the one file a user might reach for first. That is a real, contained organization gap, placing this at anchor 4 rather than 5. |
Suggestions:
- Fix the 'Full Compiled Document' section: either add the expanded AGENTS.md to the bundle or remove the section, since the pointer currently leads to a nonexistent file.
- Tighten redundant passages: collapse the three-sentence 'implementation order, not a pick-one list' restatement into one sentence, and de-duplicate the lateral-navigation guidance shared between the 'Choosing Animation Style' table and the paragraph that follows it.
- Add an explicit verification step to the body's workflow (e.g., after implementation, confirm animations fire in Chromium 125+/Firefox 144+/Safari 18.2+ and that unsupported browsers skip them silently) so the sequence has a checkpoint without requiring a trip to the reference files.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | The description names the concrete API primitives ("React's View Transition API (<ViewTransition> component, addTransitionType, and CSS view transition pseudo-elements)") and enumerates multiple specific actions — "add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js" — giving comprehensive coverage of the capability surface. This matches the anchor for multiple specific concrete actions; score 4 ('several specific actions, minor gaps') fits less well since the action list is exhaustive for the API rather than partial. |
| completeness | █████ 5/5 | Both questions are answered explicitly: the 'what' ("Guide for implementing smooth, native-feeling animations using React's View Transition API...") and the 'when' via two explicit trigger clauses ("Use this skill whenever the user wants to..." and "Also use when the user mentions...") with concrete trigger phrases. This is a direct match for anchor 5; anchor 4 would require the 'when' to be less explicit, which it is not. |
| trigger term quality | █████ 5/5 | Trigger terms cover both natural user phrasings ("page transitions", "route changes", "shared element animations", "animate list reorder", "animating between UI states in React") and exact technical tokens a user would paste ("startViewTransition", "ViewTransition", "transition types", "Next.js"). Coverage is comprehensive with synonyms; nothing common is missing, matching the top anchor rather than anchor 4's 'a few natural terms missing'. |
| distinctiveness conflict risk | █████ 5/5 | The description carves a clear niche — React's native View Transition API — and even disambiguates from the nearest competing category ("animating between UI states in React without third-party animation libraries"), so it will not trigger for framer-motion/CSS-animation skills. Distinct triggers ("startViewTransition", "ViewTransition") minimize conflict risk, matching anchor 5. |
plugins/vercel-sandbox/.agents/skills/sandbox/SKILL.md
Highly actionable and well-sectioned reference content that is weakened by its monolithic structure — roughly 1,270 lines inlined into SKILL.md with zero progressive disclosure, plus some repeated facts and verbose prose. Splitting the reference material into bundle files and deduplicating repeated limits would address the two lowest-scoring dimensions.
Validation
⚠️ skill_md_line_count — SKILL.md is long (1272 lines); consider splitting into references/ and linking
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | The ~1,270-line body is dense and mostly non-redundant per token, but repeats facts (15-port and 5-tag maxima appear in code comments, prose, and the limitations table; the sudo apt-get install pattern appears in both "Root Access" and "System Packages") and carries wordy prose sections (fork vs. drive), so it could be significantly tightened. |
| actionability | █████ 5/5 | Copy-paste-ready, executable TypeScript and CLI commands throughout (e.g., full Sandbox.create/getOrCreate/fork examples, the CLI quick reference), covering all common cases with concrete options and expected outputs. |
| workflow clarity | ████░ 4/5 | "Common Patterns" provide clear, sequenced workflows with exit-code checkpoints (e.g., "if (install.exitCode !== 0) throw new Error('Install failed')"), but the dev-server pattern never verifies the server is actually up and destructive operations (delete, --rm) lack verification steps. |
| progressive disclosure | ██░░░ 2/5 | No bundle files exist; the entire CLI reference, network policy, multi-user, and snapshot material is inlined in SKILL.md. Despite good section headers, this matches the anchor for content that clearly belongs in separate files being inlined, with no references or disclosure layers at all. |
Suggestions:
- Split the body into one-level-deep reference files (e.g., references/cli.md, references/network-policy.md, references/multi-user.md, references/snapshots.md) and keep SKILL.md as a concise overview with clearly signaled links, per progressive disclosure best practice.
- State each limit once (15 ports, 5 tags, 2048 MB per vCPU, default timeout) in the Limitations table and remove the duplicates from code comments and inline prose.
- Compress prose sections like "When to fork a sandbox or a drive" into a short decision rule (fork sandbox for full environment; fork drive for writable persistent files) and drop the inline apt-get example that repeats the "Root Access" section.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | ███░░ 3/5 | "Creates isolated Linux MicroVMs using Vercel Sandbox SDK" names the domain and one concrete action, but lists no other capabilities (running commands, snapshots, network policy), matching the anchor for 1-2 concrete actions without comprehensive coverage. |
| completeness | █████ 5/5 | Explicitly answers both what ("Creates isolated Linux MicroVMs using Vercel Sandbox SDK") and when ("Use when building code execution environments... or when the user mentions 'sandbox', 'microvm'...") with concrete trigger phrases, matching the top anchor. |
| trigger term quality | █████ 5/5 | Covers natural terms comprehensively — "sandbox", "microvm", "isolated execution", "@vercel/sandbox" — plus scenario phrases users would naturally say ("running untrusted code", "spinning up dev servers", "testing in isolation"), including the exact package identifier. |
| distinctiveness conflict risk | █████ 5/5 | "Vercel Sandbox SDK" and "@vercel/sandbox" establish a clear niche with distinct, vendor-specific triggers; minimal risk of firing for a different sandboxing skill. |
plugins/vercel-sandbox/agent/skills/sandbox/SKILL.md
Excellent actionability with dense, executable, current-version-specific guidance and no filler — but it is a monolithic 1270-line API reference stuffed entirely into SKILL.md. Splitting the CLI quick reference, advanced network policy, and multi-user/drive material into one-level-deep reference files would cut the token cost dramatically while preserving the strong quick-start material.
Validation
⚠️ skill_md_line_count — SKILL.md is long (1274 lines); consider splitting into references/ and linking
Full review details
Validation Checks
15/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███░░ 3/5 | The prose is dense and assumes competence (comments carry API facts, no beginner padding), but at ~1270 lines the body inlines a full API dump — a 130-line CLI quick reference, L7 network matchers, multi-user/groups, and drive-forking details — much of which is unneeded at trigger time. Mostly efficient but could be significantly tightened by moving bulk reference material out of SKILL.md. |
| actionability | █████ 5/5 | Copy-paste-ready, executable TypeScript throughout: creation options with real values, exit-code checks, await using cleanup, kill signals, env-var auth, AbortSignal cancellation, and complete worked patterns (dev server, build-and-test, base+fork). Specific examples cover the common cases exactly as the anchor-5 example does. |
| workflow clarity | ████░ 4/5 | The bulk is reference-style rather than a sequenced workflow, but the Common Patterns section shows clear sequences with explicit checkpoints ("if (install.exitCode !== 0) throw new Error('Install failed')") plus a dedicated error-handling section. This fits anchor 4 — clear sequence with most checkpoints — while the un-sequenced API-reference portions keep it from 5. |
| progressive disclosure | ███░░ 3/5 | No bundle files exist; everything is inlined in one ~1270-line file with zero pointers to separate references, matching anchor 3 ("content that should be separate is inline"). It avoids a 2 only because the section headers are clear and consistent, making the monolith genuinely navigable. |
Suggestions:
- Split the ~130-line CLI Quick Reference into a separate references/cli.md and keep only a handful of the most common commands (create, exec, ls, stop, remove) inline.
- Move advanced networking (L7 matchers, credential brokering, forwardURL proxying) and the multi-user/groups and drive-forking sections into one-level-deep reference files, leaving brief summaries with pointers in SKILL.md.
- Condense the 'What changed in v2' section to the migration essentials (name instead of sandboxId, persistence default) and trim the exhaustive limitations/regions tables to the values that differ from defaults.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | ████░ 4/5 | Names concrete actions ("Creates isolated Linux MicroVMs using Vercel Sandbox SDK") plus specific use cases ("building code execution environments, running untrusted code, spinning up dev servers, testing in isolation"), matching the several-specific-actions anchor. It stops short of 5 because capabilities like persistence, snapshots, and forking are not hinted at. |
| completeness | █████ 5/5 | Explicitly answers both questions: the "what" ("Creates isolated Linux MicroVMs using Vercel Sandbox SDK") and the "when" with a concrete "Use when..." clause listing concrete trigger phrases, mirroring the anchor-5 example structure. |
| trigger term quality | ████░ 4/5 | Includes natural terms users would say — "sandbox", "microvm", "isolated execution", "dev servers", "untrusted code", and the package name "@vercel/sandbox" — giving good keyword coverage. Missing common synonyms like "VM", "ephemeral environment", or "throwaway environment" for a 5. |
| distinctiveness conflict risk | █████ 5/5 | Clear niche (Vercel Sandbox) pinned by the highly specific "@vercel/sandbox" trigger; the remaining terms are strongly associated with this domain, so conflict risk with other skills is minimal. |
To improve your score, point your agent at the Tessl optimization guide. Need help? Jump on our Discord.
Feedback
Report issues with this review at tesslio/skill-review, or send private feedback from your terminal with tessl feedback.
Merged
|
PR author is in the excluded authors list. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated refresh of vendored skills.sh skills to their latest upstream versions.
Updated lock directories:
plugins/agent-browserplugins/dev3000plugins/emulateplugins/firebaseplugins/mastraplugins/nuxt-uiplugins/orpcplugins/portlessplugins/reactplugins/tsdownplugins/vercel-sandboxplugins/vinextplugins/workflow-sdkGenerated by
.github/workflows/update-skills.yml→scripts/update-skills.ts.Summary by cubic
Updates vendored skills across 13 plugins to their latest upstream versions from vercel-labs/skills. This is an automated refresh generated by
.github/workflows/update-skills.yml→scripts/update-skills.ts; each plugin'sskills-lock.jsonhashes are updated to match.Behavioral changes worth noting
gemini-2.0-pro/gemini-2.0-flash; the removedcli_commands.mdreference is replaced by inline rollouts guidance.#contentto#part.react/react-dom19.3+, so canary installs are no longer required.vercel-sandboxdrops the--stopexec flag in favor of a separatesandbox stopcommand and adds detached command management.Written for commit 2ab94d1. Summary will update on new commits.