Add blocks-api skill and npx skills install scaffolding

[cubeorgdev]

What this is

Bootstraps BlocksOrg/skills as a repo installable with the npx skills add paradigm and ships the first skill, blocks-api.

main was seeded with a single Initial commit (MIT LICENSE and .gitignore) so this PR has a base branch. Everything else lives in this PR.

Install

npx skills add https://github.com/BlocksOrg/skills --list
npx skills add https://github.com/BlocksOrg/skills --all --global
npx skills add https://github.com/BlocksOrg/skills --skill blocks-api --global

Or the one-liner: curl -fsSL https://raw.githubusercontent.com/BlocksOrg/skills/main/install.sh | sh

Layout

skills/blocks-api/SKILL.md                                 index: setup, table of playbooks, error table
skills/blocks-api/references/sessions-get-overview.md      playbook: get up to speed on an existing session
install.sh                                                 npx presence check + npx skills add --all --global --yes
README.md                                                  install, skills table, verify prompt, docs link

SKILL.md is deliberately an index. Each reference file is one ordered walkthrough for one task; new capabilities get a new row in the table and a new reference file. Endpoint, parameter, and field detail is left to the public docs so the skill does not go stale.

What blocks-api covers today

sessions-get-overview.md: fetching an existing session by ID, in the order an agent should do it:

1. Session metadata (title, pull_requests, plan_artifact_ids, _links.messages).
2. Latest plan download via plan_artifact_ids[-1] and the artifact endpoint (presigned URL, no auth header).
3. Transcript overview in one call: ?type=message&role=user&role=assistant, with the two-call fallback for deployments where role is single-valued.
4. Tool-call detail (type=tool_call, JSON-encoded message), outcomes-only (type=final_message), single-thread reads, and gts polling.

Verified against dev

• npx skills add . --list and npx skills add https://github.com/BlocksOrg/skills --list both discover exactly one skill, blocks-api.
• Every curl example was run against the dev API. Fallback overview, tool-call, final-message, thread, validation, and auth examples return the documented status codes.
• sh -n install.sh passes.

One quirk surfaced during verification and is documented in the playbook: _links.self.href and _links.new_messages.href drop type and thread_id (the latter keeps only gts), so polling and pagination URLs must be rebuilt with your own filters.

Dependency

The one-call overview (role=user&role=assistant), plan_artifact_ids, and GET /sessions/{id}/artifacts/{artifact_id} ship with orchestration-svc #1486 (docs: client-monorepo #937). Until that is deployed those calls return 422 and 404 respectively on dev. The playbook documents the fallback, so it works on both sides of that deploy.

Out of scope

Create session, follow-ups, non-plan file artifacts, plugin manifests, CI validation workflow, release tagging.

Review comments

None picked; all resolved with re-ranked severity replies.

• Not picked: plan step plan_artifact_ids[-1] yields "null" when empty (7 → 4) — out of scope
• Not picked: tool-call example 422s before #1486 deploys (7 → 4) — out of scope
• Not picked: Setup note pointing 422s to the fallback (7 → 4) — out of scope
• Not picked: description grammar "working with the Blocks" (7 → 3) — out of scope
• Not picked: fallback second call should add role=assistant (7 → 2, invalid) — out of scope

🤖 Generated with Claude Code

[cubeorgdev]

This pull request was created from a Blocks session.

View in dashboard | View on desktop

[AlejandroEsquivel]

@cube /claude /reviewreview

[cubeorgdev]

None of the five review comments block the merge. All five came from the review bot at 7/10; my independent scores run 2–6, and both comments I sent for deeper checking dropped to 4. Two comments are valid as written, one is valid but its suggested fix would lose data, one has the right fix on a wrong premise, and one is invalid.

#	File:line	Comment (short)	Bot	My score	After subagent	Verdict
1	skills/blocks-api/references/sessions-get-overview.md:28-35	Plan step: jq '.plan_artifact_ids[-1]' turns an empty result into the string "null", then a 404, then a silent curl null	7	6	4 (6→4)	Valid; premise partly wrong
2	skills/blocks-api/references/sessions-get-overview.md:58	Tool-call example with role=user&role=assistant returns 422 before the multi-role role change (orchestration-svc #1486) is deployed	7	5	4 (5→4)	Valid; suggested fix would lose data
3	skills/blocks-api/SKILL.md:17-23	Setup should say a 422 means #1486 isn't deployed yet and point to the fallback	7	4	not checked (<5)	Partly valid (nice to have)
4	skills/blocks-api/SKILL.md:4	Description reads "working with the Blocks", which is broken grammar	7	3	not checked (<5)	Valid (cosmetic)
5	skills/blocks-api/references/sessions-get-overview.md:54	Second fallback call should be ?type=message&role=assistant	7	2	not checked (<5)	Invalid

What I found

#1, plan step (6 → 4).

• The failure is real. jq -r '.[-1]' prints null for an empty list, a null value, or a missing key alike. The artifact call then 404s and curl -s null exits 6 with no output, so nothing tells the agent the step failed.
• The premise is wrong. #1486 types the field as an array and defaults it to [], with a test asserting [] for a session with no plans. It is never null. On dev today the key is simply missing, because #1486 isn't merged.
• The suggested // empty is the right fix, but it also needs an explicit [ -n "$PLAN_ARTIFACT_ID" ] guard to stop the next two calls.
• The score dropped because the text already says to skip the step when there's no plan, and the endpoint isn't live yet.

#2, tool-call example (5 → 4).

• Confirmed: the example returns 422 on dev. main still accepts a single role; #1486 (open) makes it repeatable.
• The reviewer's fix (?type=message&type=tool_call) is lossy. Without a role filter you get assistant items only: 93 messages and 143 tool calls, but 0 of the 19 user prompts.
• A better fix is to keep the role filters and extend the 422 fallback to cover the tool-call case.
• The score dropped because the existing fallback note already names the exact role=user&role=assistant pattern, and the problem goes away once #1486 deploys.

#3, Setup note. An agent hitting 422 does reach the fallback in the playbook. A one-line pointer in Setup is cheap but not required.

#4, description grammar. The wording is real, but that description is your verbatim text from the last round. It only affects how the listing reads, not whether the skill triggers correctly.

#5, fallback call. The comment contradicts itself mid-sentence ("…actually also matches on role"). I checked on dev: ?type=message and ?type=message&role=assistant both return the same 93 assistant items, because the default role is already assistant. The "89 vs 50" in the comment comes from comparing a full result with a page capped at the default limit=50, not from any difference in the data. Adding role=assistant would only make the call more explicit.

Next step

I haven't changed any code, PR comments, or the PR description. Tell me which numbers to fix (e.g. "1, 2"). Then I'll:

1. fix and push the picked issues, and resolve their comments;
2. reply to each unpicked comment with why its score changed, and resolve it;
3. add a "Review comments" section at the bottom of the PR description, one line per comment, marking it picked or not (with your reason, or "out of scope" if you don't give one).

View on dashboard

[cubeorgdev]

User Message:

not adressing, continue

I replied to all five review comments and resolved each one. Since you didn't pick any, no code changed and nothing was pushed.

Replies: each reply says the comment is out of scope and explains why its severity changed:

Comment	Severity	Reason given in the reply
Plan step turns an empty plan_artifact_ids into "null"	7 → 6 → 4	The API returns [], never null, so the comment's premise is wrong. The silent-failure path is still real, but the docs already say to skip the step when there's no plan.
Tool-call example 422s before orchestration-svc #1486 deploys	7 → 5 → 4	The 422 is real. The suggested fix would drop all 19 user prompts, and the existing fallback already covers this pattern.
Setup should point 422s to the fallback	7 → 4	The playbook's fallback is keyed on that exact 422, so the pointer would be a nice extra.
Description grammar	7 → 3	Cosmetic, and it's the text you supplied.
Fallback should add role=assistant	7 → 2 (invalid)	role already defaults to assistant; on dev both forms return the same 93 items.

PR description: I added a "Review comments" section at the bottom, with one line per comment marked not picked and out of scope. gh pr edit failed on GitHub's classic-Projects deprecation error, so I updated the description through the REST API instead.

View on dashboard

[cubeorgdev]

The third link in this Docs section is dead: https://docs.blocks.team/rest-api/sessions/artifacts returns 404 today, and the docs site's sitemap / quick-start page contain no artifacts page at all — it presumably ships with the client-monorepo #937 docs you reference in the PR body, at a path that's still a guess until that lands. Unlike the API calls, there's no fallback covering the pre-deploy side here: the skill deliberately delegates endpoint/field detail to the public docs, so once this merges, an installed agent that follows this link for artifact detail gets a 404 with nowhere to go. Suggest either dropping the line until the page exists, pointing at the quick-start in the meantime, or re-verifying the final URL against #937 before merge so the path matches what actually ships.

Severity 7/10 · View on dashboard · PR Review Settings

💡 Tip: You can disable PR Review for Draft PRs in PR Review Settings