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 or finalize a pull request — three modes: placeholder draft PR at spec time, finalize a draft into ready-for-review, or a regular PR right away for work done outside the task workflow.

Grill a product task (GitHub issue) into an implementable spec — research first, then a one-question-at-a-time interview; also elaborates sub-specs for big steps of large tasks.

Execute a product-task spec one leaf subtask per run — [agent] subtasks via the project skills, [human] subtasks handed off to the developer.

Convert the current conversation into a product-task spec in .agents/tasks/, or update an existing spec — folding in new decisions, harvesting colleague replies from Slack threads, and sending open questions to their owners. Use at the end of a grilling session, when the user wants to capture any conversation as a spec, or to sync a spec's open questions with Slack.

Declare new API resource(s) in an existing API service. Use whenever the app needs to call an endpoint that has no `service:name` resource yet.

Scaffold a new page (index / detail / general) and optionally wire it to API data. Use when adding any new route to the app, or when wiring API data into an already-scaffolded page (one with `TODO (api-data):` markers).

Publish a beta version of a `@blockscout/*-types` npm package and pin it here. Use when a needed response type isn't in any published package version yet.

Resolve the real request URL of an API resource on a live Blockscout instance (`service:name` + instance → full URL). Use whenever a request must be made to, or a sample response fetched from, a deployed instance's API.

Enter the worktree of a GitHub PR, validate the code-review comments raised on it against what the code actually does and the repo rules, fix the valid ones directly in the PR's source/tests, and report in chat — a brief note per closed comment and a detailed plain-language explanation of every comment left unclosed and why. For code-review comments on a PR. Invoke manually.

Validate review findings about an implementation plan against the codebase and repo rules, fix the valid ones in the plan, and write a feedback file noting what changed and what was rejected (and why). For plan-review findings, not code-review findings.

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

Publish a GitHub issue from a markdown file in .ai/gh_issues/ created by gh-issue-bug or gh-issue-improvement skills

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.

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.

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.