blockscout

Turn an approved task-analysis result into a shared technical design and coding-ready implementation handoff; use when Claude has an existing task folder under `tmp/tasks/`, plus a selected solution and related codebase research, and needs to produce `implementation-plan.md` and `coding-task.md` before writing code

Prepare a pull request description from task artifacts under `tmp/tasks/<task-name>/` and the current implementation snapshot. Use when Claude needs to draft or refresh a Markdown PR description before review, handoff, or merge, including implementation summary, API changes, environment or configuration changes, database or migration impact, testing, and rollout notes.

Investigate and document the intended scope of a codebase topic through interactive discussion, then persist a durable research note under .memory-bank/research/ once the human confirms the framing

Review already-applied code changes against the original task statement or task folder artifacts under `tmp/tasks/<task-name>/`. Use when implementation work is done and Claude must verify scope coverage, detect mismatches or regressions, assess verification gaps, and write a review summary before handoff or merge.

Review a task, issue, or feature request before coding; persist the task framing under `tmp/tasks/<task-name>/task.md`, write one or more `solution_N.md` option files, compare them in `solutions.md` when needed, and recommend a path with explicit reasoning

Apply code changes from an existing task handoff under `tmp/tasks/<task-name>/coding-task-X.md`. Use when Claude receives a task name and coding-task index and must implement that prepared coding task strictly, without inventing missing scope or design details.

Draft a GitHub bug report from the current conversation, save it under tmp/gh-issues/, and follow the repository's canonical bug-report workflow.

Draft a GitHub improvement or enhancement proposal from the current conversation, save it under tmp/gh-issues/, and follow the repository's canonical improvement workflow.

Create, adjust, or inspect OpenAPI declarations for Blockscout API v2 endpoints. Use this skill whenever the user asks to: add an OpenAPI spec to an endpoint that lacks one, update a spec after controller/view changes, audit or fix an existing OpenAPI declaration, or work with open_api_spex annotations in the Blockscout codebase. Also trigger when the user mentions 'swagger', 'openapi', 'open_api_spex', 'API spec', 'API schema', or 'operation macro', or when debugging failures like 'response schema mismatch', 'CastAndValidate rejection', 'json_response validation error', 'Unexpected field', or extra/missing keys in API responses.

Use when refactoring Elixir multi-clause functions, extracting helper functions, or fixing Credo readability warnings caused by placing `defp` helpers between clauses of the same function. Keeps function clauses contiguous and moves helpers below the full clause group.

Ensure every newly introduced environment variable is also added to docker-compose/envs/common-blockscout.env so local Docker setups stay aligned with runtime configuration.

Replace `with` expressions that contain only a single `<-` clause and an `else` branch with a `case` expression. This addresses the Credo warning "with contains only one <- clause and an else branch, consider using case instead" and produces cleaner, more idiomatic Elixir code.

Use when working on Elixir code with Credo predicate naming warnings, boolean helper functions, or renaming functions that start with is_. Prevents violations like: Predicate function names should not start with 'is' and should end in a question mark.

Define module aliases at the top of the file instead of using fully qualified nested module names in function bodies. Improves code readability and maintainability while addressing Credo style warnings.

Ensure that aliases are alphabetically ordered within their groups to maintain consistent code style and address Credo readability warnings.

Fixes code formatting in the Blockscout Elixir project using mix format. Use when you need to fix formatting violations, code style inconsistencies, or ensure consistent code formatting. For linting issues, use `mix credo`. Use this skill for every change made.

Use this skill whenever you are about to run any write `gh` CLI command — `gh pr edit`, `gh pr create`, `gh issue edit`, `gh issue create`, `gh pr comment`, `gh issue comment`, `gh pr close`, `gh pr merge`, `gh release create`, or similar. High-level `gh` commands sometimes fail with "missing required scopes" auth errors even though the underlying GitHub REST API works fine with the same token. This skill makes you automatically fall back to `gh api` instead of stopping to ask the user to re-authenticate. Always invoke before running any mutating `gh` command.

Expert review of an implementation plan against a GitHub issue/enhancement description (provided as a local file or a GitHub issue URL) and the current repository codebase. Use when asked to critique a plan for correctness, completeness, codebase alignment, risks, and test/rollout readiness (do not implement).

Export a detailed phased implementation plan for a GitHub issue to a file, reading all applicable rules from .cursor/rules before planning

Use to implement a structured implementation plan (e.g. temp/impl_plans/issue-*.md) phase by phase. Trigger when the user asks to implement, execute, realize, or "do" an implementation-plan file. Orchestrates a phase-developer subagent and a plan-correspondence-verifier subagent for each phase, commits each verified phase, then walks the Final Checklist. Invoke explicitly — it makes commits and spawns many subagents.

TRIGGER CONDITIONS - invoke this skill when ANY of these apply: User-triggered (explicit request): - User mentions "specification", "SPEC", "SPEC.md", "spec requirements" - User asks to "verify with spec", "confirm with specification", "check requirements" - User requests "authoritative requirements" or "source of truth" Agent self-triggered (during reasoning): - Before implementing any feature or making code changes - When verifying technical requirements or constraints - When making architectural or design decisions - When you need unbiased guidance not influenced by current implementation - When encountering conflicting information and need ground truth PURPOSE: Consults SPEC.md through an isolated subagent that ONLY reads the specification, never implementation code. This ensures guidance is based on authoritative requirements, not potentially incorrect existing code.

Describe very high level changes required to implement discussed functionality (functionality, test, docs)

Generate a structured bug report for GitHub issues based on conversation context about bugs, errors, or broken functionality

Generate a structured improvement/enhancement proposal for GitHub issues based on conversation context

MANDATORY — invoke this skill BEFORE making any Blockscout MCP tool calls or writing any blockchain data scripts, even when the Blockscout MCP server is already configured. Provides architectural rules, execution-strategy decisions, MCP REST API conventions for scripts, endpoint reference files, response transformation requirements, and output conventions that are not available from MCP tool descriptions alone. Use when the user asks about on-chain data, blockchain analysis, wallet balances, token transfers, contract interactions, on-chain metrics, wants to use the Blockscout API, or needs to build software that retrieves blockchain data via Blockscout. Covers all EVM chains.

Refresh the bundled Blockscout API reference files inside one of this repo's end-user skills. Takes a target argument; each target has its own pipeline because the source artefacts differ (Swagger releases for `blockscout-analysis`, a build-time clone of the `pro-api` repo for `web3-dev`). Run when a target's upstream cuts a new release and the skill's bundled references need to catch up.

Build web3 applications, scripts, CLIs, bots, mobile apps, and desktop apps that need blockchain data via the Blockscout PRO API — a single HTTP API spanning 100+ EVM chains. Invoke this skill whenever the user wants to read blockchain data over HTTP (transactions, blocks, addresses, tokens, NFTs, logs, contract context, internal txs, account abstraction, etc.) and is building software that calls an API directly. Trigger on direct mentions of `Blockscout PRO API`, `pro-api`, `proapi_`, `Blockscout API`, `block explorer API`, `api.blockscout.com`, or on broader phrasing like "build a web3 app", "index/query on-chain data", "wallet history", "NFT inventory", "transaction logs across chains", "how much does the Blockscout API cost", "chain IDs supported by Blockscout". Use this skill for direct HTTP integrations; the sibling `blockscout-analysis` skill covers the Blockscout MCP Server.

Bump a skill's version number across all files in this repo (the skill's own frontmatter, the marketplace plugin entry, and any skill-specific occurrences). Pass the skill name and new version as arguments (e.g., 'blockscout-analysis 0.5.0'). Use after content changes are complete and the skill is ready for a new release.

Execute a migration task from a GitHub issue through to a PR, or fix unresolved review comments on an existing migration PR. Reads scope and acceptance criteria from the issue body.

Research a migration task, create a GitHub sub-issue with scope and acceptance criteria, and update the task backlog. Takes a task ID from docs/MIGRATION_TASKS.md, explores the codebase, creates an issue in blockscout/frontend, links it to the parent migration issue, and commits the status update.

Create a well-structured pull request with proper description, labels, and reviewers