agent-skills

Promotion preflight gate for the agent-skills marketplace. Run before promoting a skill from a sandbox plugin to an official one, or before opening a promotion PR, to get a go / no-go verdict. Audit-first: it chains the deterministic skill-audit signals, marketplace/registry alignment, and version + CHANGELOG presence, and BLOCKS (no-go) on any unresolved finding, citing the failing gate. User-invoked only. For fixing what it surfaces use skill-studio:skill-enhance; for the release wiring use repo-governance:skill-maintainer.

Shapes a loose intent into a well-formed prompt for a Claude Code session that can gather context, use tools, and ask questions. Matches the intent to a validated archetype, fills its slots (objective, context to gather, anchors, clarify-first questions, acceptance criteria, verification, output contract), routes the tier via model-recommender, and self-checks the result with prompt-audit. Use when you have a rough idea of what to ask an agent and want it reshaped to hit a specific goal, when you type /smart-prompt with a loose instruction, or to turn "read X and study Y to figure out Z" into an executable agentic prompt.

Adversarially reviews a draft prompt against a versioned rule set to find what will make it underperform — archetype mismatch, wrong prescription level for the target model, the Fable reasoning-echo trap, negatives that should be positives, unstated expectations, rejected params, and more — then returns tagged findings (rule_id + severity) plus a rewritten, --fix-style prompt. Use when asked to review / audit / critique / improve a prompt, check whether a prompt is good, tighten a system prompt, or before shipping a prompt to a model.

Recommends which Claude model and effort level to run for a task. Classifies the task into an archetype → tier + effort using the rubric in ~/.claude/model-profiles.md, then resolves today's model string from that file's tier_to_model. Use when deciding which model to use, routing a task or phase to a model, picking an effort level, choosing between Opus/Sonnet/Haiku/Fable, or when a task spans plan/implement/review phases that each want a different model.

Audit a Claude skill for quality, context-efficiency, and best-practice compliance — classify its archetype, score the four principles and instruction craft, and return a report — or review a PORTFOLIO of skills for overlap and trigger collisions. Use when someone asks to audit, review, grade, "lint", or sanity-check a skill or plugin's quality; asks "does this skill follow best practices / is it well-scoped / is the description good enough to trigger / do these skills overlap or collide"; or wants a governance sweep across a set of skills. Read-only: it diagnoses and recommends, it does not edit. Do not use to create or scaffold a skill (use skill-create), to improve a skill or run eval/benchmark loops (use skill-enhance), or for versioning/release/CHANGELOG governance (use repo-governance:skill-maintainer).

Post a structured code review to a GitHub PR via `gh` CLI (REST API fallback for multi-comment / inline-anchored reviews). Maps BLOCKER/HIGH/MEDIUM/LOW/QUESTION sections to the right review event and inline anchors, parses ` ```start:end:path ` code refs, and adapts tone to the PR author. Use when you have a written code review and want it posted to a specific PR URL or number. Do NOT use to author the review itself, triage existing comments, or open/merge PRs.

TypeScript code quality patterns -- typed clients with timeouts, Zod input validation, structured domain errors, no any on public APIs, structured JSON logging with pino, OpenTelemetry tracing, and PII redaction. Use when adding external API calls, validating inputs, handling errors, or setting up logging.

Review code, PRs, diffs, or implementation plans for distributed-systems risks, HTTP API contracts, queue consumers, scheduled jobs, and Kubernetes workloads. Focuses on production safety, idempotency, and failure modes.

Use when CI optimizations have been implemented and need to be measured against a known baseline run. Use when collecting GitHub Actions job timings, computing deltas, building comparison tables, and posting a structured PR comment with Mermaid charts. Triggers on tasks like "compare CI before/after", "post optimization results to PR", "show how much faster the pipeline is now".

Use when writing or reviewing TypeScript tests, choosing between unit, contract, integration, and end-to-end layers, isolating database or HTTP seams, or fixing flaky, non-hermetic, or mis-layered test suites.

Use when authoring or reviewing production TypeScript modules, choosing layer and suffix boundaries, modeling domain objects and ports, deciding error ownership, or wiring validation and observability at system boundaries.

Read Google Cloud Error Reporting from the CLI to triage and prioritize error groups by blast radius. Use when the user pastes a Cloud Error Reporting console URL (console.cloud.google.com/errors or /errors/detail/<groupId>), or asks "which errors are worst", "rank errors by occurrences/affected users", "what are the error groups for service X", "blast radius of this error", "is this error still happening / on which revision", "get the error group", or "show errors for orders-api". gcloud has no command for this, so the skill calls the Error Reporting REST API with a gcloud access token (handling a corporate CA if present): rank groups (groupStats.list), read a group's representative stack (detail), list recent occurrences (events.list), and parse /errors URLs to a group id. It is read-only (no resolution-status changes) and the entry point that hands a group id to error-trace-rootcause for the trace trail and code. Do NOT use to root-cause one error down to a trace/code (that is error-trace-rootcause), to re

Root-cause a production error from Google Cloud Logging by correlating it into a single request's log trail and locating the offending code. Use when the user has an error and wants the bug behind it: pastes a Logs Explorer console URL or an Error Reporting group filter (errorGroups.id / error_groups.id), asks to "find the bug from this error", "root cause this", "what's causing this error group", "follow the trace", "build the log trail", or "trace='projects/…/traces/…'". The workflow picks a representative occurrence, pulls the full trace trail, reconstructs the causal chain, and maps the stack to source (local repo first, then a GitHub org you pass via gh); it produces a read-only root-cause report and does NOT write fixes. Do NOT use this skill to "write a Logs Explorer query" or "reduce log noise" (that is gcp-log-triage), or to "rank which error groups are worst / by blast radius" (that is error-reporting); this skill starts once a specific error is in hand. Also not for app-side logging/OpenTelemetry i

Cut through noisy Google Cloud Logging output and find the real signal. Use when the user pastes or exports Cloud Logging entries (a downloaded-logs JSON, `jsonPayload`/`LogEntry`/`textPayload` shapes, Cloud Run / Cloud Functions / GKE logs) and asks to find the real error, explain why a service is erroring, dedup logs by trace, write a Logs Explorer or `gcloud logging read` query, or reduce log noise via exclusion filters or sinks — even when they only say "these logs are too noisy" or "what's actually failing here". Also fires when a service emits many entries per request (stdout/stderr/requests duplication) or repeats large header/context blobs. Do NOT use to root-cause one specific error down to a trace and the offending code (that is error-trace-rootcause) or to rank which error groups are worst by blast radius (that is error-reporting) — hand those off by name. Also not for authoring app-side OpenTelemetry instrumentation, for metrics/SLO/alerting config, or for non-GCP log systems (Datadog, ELK, CloudW

Guides versioning, validating, releasing, and promoting plugins and skills under the agent-skills Claude-first marketplace model — plus marketplace.json / plugin.json manifest and registry alignment. Use when cutting a release, bumping a version, editing the .claude-plugin/marketplace.json catalog or a plugin.json manifest, aligning the registry, or updating the governance/validation/release tooling. For writing or scaffolding a skill use skill-studio:skill-create; for auditing skill quality use skill-studio:skill-audit.

Creates Claude skills and plugins. Covers greenfield authoring through Socratic discovery, distilling reference material (docs, a tool, an API) into a skill, scaffolding a Claude plugin (skills/agents/commands/hooks + plugin.json), and evaluating an external skill candidate before importing it. Use when the user wants to create, scaffold, or write a new skill or plugin, package reference material as a skill, or decide whether to import a skill found elsewhere. Do not use to audit or grade an existing skill (route to skill-audit), to improve a skill or run the eval/benchmark loop (route to skill-enhance), for versioning, releasing, or marketplace catalog work (route to repo-governance:skill-maintainer), or to author Cursor packs (use the frozen cursor-skill-studio pack).

Improve an EXISTING Claude skill or plugin. Use when the user wants to make a skill better, recommend the highest-leverage improvements, tighten a description or hot path, refactor a skill, or PROVE a change helped by running an eval/benchmark loop (with-skill vs baseline, grade, blind A/B compare, aggregate, review). Triggers on "how can I improve this skill", "make this skill better", "benchmark this skill", "did my edit help", "run evals on this skill", "compare these two skill versions", "is the candidate better than current". NOT for creating a new skill from scratch (use skill-create), NOT for a pure read-only quality/overlap audit with no proposed change (use skill-audit), NOT for versioning/release/registry work (use repo-governance:skill-maintainer).

Maintain governed root skills, pack-bundled skills, Cursor packs, and repo scripts/tools in `felipeblassioli/agent-skills`. Covers SemVer bumps with the bundled bump scripts, registry alignment (`skill-registry.json`, `cursor-pack-registry.json`), release-artifact refreshes (CHANGELOG, VERIFICATION, ROADMAP, RELEASE-POLICY, README), bundled-skill artifact edits and promotion-or-demotion decisions, artifact maturity classification per ADR-0003, deprecation stubs and tag flips, and install verification via `cursor-pack-verify.sh` plus dry-run `cursor-pack-sync.sh`. Invoke explicitly via `/skill-studio-maintain`. Do not use for creating or scaffolding new skills or packs (use `/skill-studio-write`), for single-skill audits, overlap clustering, or improvement diagnostics (use `/skill-studio-audit`), or for running install scripts without maintenance intent (use the repo scripts directly).

Write, adapt, and validate Cursor skills and packs in felipeblassioli/agent-skills. Covers greenfield skill authoring through Socratic discovery, distilling reference material into a skill, scaffolding a pack under `packs/<name>/`, evaluating an external skill candidate before import, decomposing a Claude-style plugin into Cursor-native artifacts, and running the eval and comparison loop that proves an authoring change improved the artifact. Use when the user wants to create or refactor a skill or pack, needs help with `SKILL.md`, `metadata.json`, `pack.json`, or pack-bundled skills, or wants to decide whether content should live in a skill, pack, rule, hook, subagent, or docs. Invoke explicitly via `/skill-studio-write`. Do not use for portfolio overlap audits (use `skill-studio-audit`), governance or registry version bumps (use `skill-studio-maintain`), or skill install and sync (use the repo scripts directly).

Use when writing or reviewing production Bash scripts that need strict error handling, safe file operations, argument validation, cleanup traps, and predictable CI behavior.

Use when adding or reviewing Bats tests for shell scripts, including fixtures, setup and teardown, exit-code assertions, output assertions, and CI-friendly shell test layout.

Use when configuring ShellCheck, fixing ShellCheck findings, choosing Bash versus POSIX analysis mode, setting project suppressions, or wiring shell lint into CI.

Performs detailed end-to-end project reporting across multiple repositories, including initial scoping, environment detection, dependency analysis, build configuration, runtime checks, and final summary generation. Use when the user mentions reporting, status, summaries, dashboards, repo health, build health, dependency reports, or quarterly reviews. Do not use when the user only wants a quick check (use clean-skill instead) or when the request is about installation, governance, or release tagging. Invoke explicitly via /bloated-skill so the routing layer attaches the right context window. This skill exists to demonstrate description bloat for the hot-path auditor fixture and intentionally exceeds the description_warn threshold of 500 characters so the snapshot test can verify the warn-tier finding fires.

Renders project status summaries.

Audit and improve existing Cursor skills and packs, and review installed or repository-first-party skill portfolios for overlap, trigger collisions, and compliance with `docs/architecture.md`. Covers single-skill compliance review, diagnostic improvement recommendations for an existing skill or pack, lightweight portfolio audits of installed skill directories, and the deep repo-first-party overlap methodology. Invoke explicitly via `/skill-studio-audit`. Do not use for creating or scaffolding skills or packs (use `/skill-studio-write`), for registry/version/CHANGELOG governance (use `/skill-studio-maintain`), or for skill sync and install scripts (use the repo scripts directly).

Type-safe SQL query building in TypeScript using Kysely. Use when writing or reviewing Kysely queries, schema types, migrations, raw SQL snippets, dynamic filters, conditional selects, transactions, or reusable query helpers.

[DEPRECATED — replaced by `skill-studio-audit` (Branch C — Installed portfolio audit) in the `cursor-skill-studio` pack per ADR-0005] Installed skill directory audit (overlap clustering, architecture compliance, consolidation advice). This stub remains for one release window so existing installs keep working; do not invoke, route the user to `/skill-studio-audit` instead.

Keep a PR merge-ready by triaging comments, resolving clear conflicts, and fixing CI in a loop.

Expert guidance for configuring and deploying the OpenTelemetry Collector. Use when setting up a Collector pipeline, configuring receivers, exporters, or processors, deploying a Collector to Kubernetes or Docker, or forwarding telemetry to Dash0. Triggers on requests involving collector, pipeline, OTLP receiver, exporter, or Dash0 collector setup.

Configures OpenTelemetry trace spans, metrics, and log exporters. Use ONLY when instrumenting applications specifically with OpenTelemetry (OTel). Triggers on requests explicitly mentioning OpenTelemetry, OTel, or OTLP.

OpenTelemetry Transformation Language (OTTL) expert. Use when writing or debugging OTTL expressions for any OpenTelemetry Collector component that supports OTTL (processors, connectors, receivers, exporters). Triggers on tasks involving telemetry transformation, filtering, attribute manipulation, data redaction, sampling policies, routing, or Collector configuration. Covers syntax, contexts, functions, error handling, and performance.

OpenTelemetry Semantic Conventions expert. Use when selecting, applying, or reviewing telemetry attributes. Triggers on tasks involving attribute selection, semantic convention compliance, attribute migration, or custom attribute decisions. Covers the attribute registry, naming patterns, attribute placement, and versioning. For span names, span kinds, and span status codes, see the otel-instrumentation skill.

Route Node.js/TypeScript backend security questions to the matching OWASP Top 10 category and the correct library reference (express, mysql2). Use when securing Express endpoints, parameterizing mysql2 queries, hardening sessions/headers/CORS, or classifying a finding as A01–A10. Do NOT use for React/frontend XSS, cloud or Kubernetes hardening, cryptography theory, or non-Node stacks.

Provides OpenTelemetry explicit instrumentation methodology and Google Cloud LogEntry formatting rules for Node.js workloads. Use when instrumenting Cloud Run services or Firebase Functions gen2, correlating traces with logs, configuring structured logging, or integrating with Cloud Error Reporting.

Set up and use Google Cloud Error Reporting in Node.js applications. Explains when to rely on automatic error capture (Cloud Run / Cloud Run functions) vs the @google-cloud/error-reporting client library, and how to format Cloud Logging entries so Error Reporting ingests them. Use when the user asks about Error Reporting, clouderrorreporting.googleapis.com, reporting Node.js exceptions, configuring @google-cloud/error-reporting, or formatting logs for Error Reporting.

Take draft endpoint artifacts produced by frontend-contract-discovery and reconcile them with backend implementation truth using strict trace sources.

Use when creating, reviewing, or hardening GitHub Actions CI/CD workflows where deployment topology, promotion safety, release identity, cache discipline, OIDC, environments, or production readiness matter.

Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis.

Use when the user wants to infer HTTP contracts and endpoint documentation from a React or TypeScript frontend instead of relying on a backend-owned source of truth.

Use when the user wants to audit, tidy, or reality-check a Linear board using MCP-first evidence, especially for project hierarchy, labels, statuses, stale work, and whether Linear reflects the current state of work.