docs(skills): contribute 14 builder reference skills under docs/skills/#707
docs(skills): contribute 14 builder reference skills under docs/skills/#707sergiosegado wants to merge 5 commits into
Conversation
These are protocol-generic Claude Code skills for builders integrating with Yellow Network — covering Nitro RPC wire format, ClearNode auth, session keys, transfers, app sessions, channels, the Custody contract, both SDK versions, and a getting-started skill that indexes the rest. They originated in the YellowHive agent platform's public skill set and are contributed back here so any builder can use them directly. Nothing in this set is YellowHive-specific (verified — zero `yellowhive` / `api-hive` references). last_verified bumped to 2026-04-26. Includes a docs/skills/README.md catalog with grouped links and frontmatter conventions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
sergiosegado
requested review from
dimast-x,
ihsraham,
nksazonov and
philanton
as code owners
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughThree new documentation files are added to the ChangesDocumentation Catalog Structure
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (11)
docs/skills/yellow-sdk-v1/SKILL.md (1)
10-13: Adddocs/api.yamltosource_urlsfor v1 canonicality.
This skill is v1-focused, so linking the repository’s canonical v1 API source will reduce drift and ambiguity. Based on learnings: Always refer todocs/api.yamlas the canonical source of truth for v1 RPC methods, types, and request/response schemas.Suggested fix
source_urls: - https://www.npmjs.com/package/@yellow-org/sdk + - https://github.com/layer-3/nitrolite/blob/main/docs/api.yaml - https://docs.yellow.org/docs/0.5.x/build/quick-start - https://docs.yellow.org/docs/0.5.x/guides/migration-guide🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/skills/yellow-sdk-v1/SKILL.md` around lines 10 - 13, The source_urls list in SKILL.md is missing the canonical v1 API reference; update the source_urls array to include "docs/api.yaml" so the v1 skill points to the repository's canonical RPC/type schemas; modify the source_urls entry in SKILL.md (the source_urls block) to add "docs/api.yaml" alongside the existing npm and docs links to ensure v1 canonicality.docs/skills/yellow-custody-contract/SKILL.md (1)
157-164: Add a language tag to this fenced block (markdownlint MD040).
This block is currently unlabeled and will keep lint warning noise.Suggested fix
-``` +```text off-chain create_channel (RPC) ─▶ ClearNode returns channel + state0 + serverSig on-chain Custody.create(channel, state0, userSig, serverSig) (2 sigs) off-chain resize_channel (RPC) ─▶ ClearNode returns stateN + serverSig on-chain Custody.resize(channelId, stateN, [userSig, serverSig]) (2 sigs) off-chain close_channel (RPC) ─▶ ClearNode returns FINALIZE state on-chain Custody.close(channelId, state, userSig, serverSig) (2 sigs)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-custody-contract/SKILL.mdaround lines 157 - 164, The
fenced code block showing the off-chain/on-chain sequence (the lines beginning
"off-chain create_channel (RPC) ─▶ ClearNode returns channel + state0 +
serverSig" through "on-chain Custody.close(channelId, state, userSig,
serverSig) (2 sigs)") is unlabeled and triggers markdownlint MD040; add a
language tag (e.g., change the openingtotext) to the fenced block in
SKILL.md so the block is explicitly marked and the lint warning is resolved.</details> </blockquote></details> <details> <summary>docs/skills/README.md (1)</summary><blockquote> `3-3`: **Minor wording polish: capitalize “Markdown”.** Use proper noun casing for consistency in docs prose. <details> <summary>Suggested fix</summary> ```diff -...Each skill is a focused markdown document with frontmatter... +...Each skill is a focused Markdown document with frontmatter... ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/skills/README.md` at line 3, Change the phrase "markdown document" to "Markdown document" in the README sentence so the proper noun casing is used; update the sentence that currently reads "Each skill is a focused markdown document with frontmatter..." to "Each skill is a focused Markdown document with frontmatter..." to maintain consistent capitalization in docs. ``` </details> </blockquote></details> <details> <summary>docs/skills/yellow-sdk-api/reference.md (1)</summary><blockquote> `255-276`: **Add explicit `docs/api.yaml` pointer in the v1 preview block.** The v1 section is useful, but adding a direct “canonical methods/types live in `docs/api.yaml`” note here will help prevent future method-name drift in this file. Based on learnings: Always refer to `docs/api.yaml` as the canonical source of truth for v1 RPC methods, types, and request/response schemas. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/skills/yellow-sdk-api/reference.md` around lines 255 - 276, Add a short, explicit pointer in the v1 preview telling readers to use docs/api.yaml as the canonical source for v1 RPC methods/types; update the paragraph around the Client/createSigners example (and the sentence that warns about dotted namespaces like channels.v1.get_home_channel, user.v1.get_balances, node.v1.ping) to append a clear note such as “Canonical v1 RPC methods and schemas live in docs/api.yaml” so future edits reference docs/api.yaml for method-name and type authority. ``` </details> </blockquote></details> <details> <summary>docs/skills/yellow-state-channels/reference.md (3)</summary><blockquote> `163-187`: **Consider adding language identifier to code block.** The challenge-response protocol steps would benefit from a language specifier (e.g., `text` or `markdown`) to suppress linter warnings. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-state-channels/reference.mdaround lines 163 - 187, The
fenced code block containing the step-by-step challenge-response protocol (the
triple-backtick block showing steps 1–3b) lacks a language identifier which
triggers linter warnings; add a language tag such astext ormarkdown
immediately after the opening backticks to suppress warnings and clarify the
block's format while leaving the block content unchanged.</details> --- `9-14`: **Consider adding language identifier to code block.** The EIP-712 domain parameter block would benefit from a language specifier (e.g., `yaml` or `text`) for better rendering. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```yaml name: "VirtualApp:Custody" ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-state-channels/reference.mdaround lines 9 - 14, The code
block containing the EIP-712 domain parameters (the lines with keys name,
version, chainId, verifyingContract) should include a language identifier for
proper rendering; update the opening triple-backticks to include a language such
as yaml (e.g., changetoyaml) so the block is highlighted correctly in
the docs.</details> --- `41-43`: **Consider adding language identifier to code block.** The channelId derivation formula would render better with a language specifier (e.g., `solidity` or `text`). <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/skills/yellow-state-channels/reference.md` around lines 41 - 43, The code block showing the channelId derivation lacks a language identifier; update the fenced code block around "channelId = keccak256(abi.encode(participants, adjudicator, challenge, nonce, chainId))" to include an appropriate language tag (e.g., `solidity` or `text`) so the expression using keccak256 and abi.encode (and the variables participants, adjudicator, challenge, nonce, chainId) renders with correct syntax highlighting. ``` </details> </blockquote></details> <details> <summary>docs/skills/yellow-nitro-rpc/SKILL.md (1)</summary><blockquote> `22-35`: **Consider adding a language identifier to the code block.** The code block showing the envelope format (lines 22-35) lacks a language specifier. While this is abstract TypeScript/JSON notation, adding `ts` or `typescript` would improve syntax highlighting and readability. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```ts // Request { ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-nitro-rpc/SKILL.mdaround lines 22 - 35, The fenced code
block that shows the envelope format for the Request/Response (the block
containing the "req"/"res" JSON-like objects and "sig" arrays) is missing a
language identifier; update the opening fence fromto a language tag such asts or ```typescript so the snippet gets proper TypeScript/JSON syntax
highlighting (leave the block contents unchanged, only add the language
specifier).</details> </blockquote></details> <details> <summary>docs/skills/yellow-deposits-withdrawals/SKILL.md (1)</summary><blockquote> `22-34`: **Consider adding language identifier to ASCII diagram.** The ASCII flow diagram would benefit from a language specifier (e.g., `text` or `mermaid` if converted) to suppress linter warnings, though the current format is clear. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-deposits-withdrawals/SKILL.mdaround lines 22 - 34, The
ASCII diagram code block lacks a language identifier which triggers linter
warnings; update the opening fenced block fromto include a language specifier liketext (or ```mermaid if you convert the diagram) so the diagram
is treated correctly by the linter and markdown renderer, ensuring the block
around the lines containing "EOA / Smart Wallet", "Custody contract", "Unified
balance (off-chain)" etc. is updated accordingly.</details> </blockquote></details> <details> <summary>docs/skills/yellow-sdk-v1/reference.md (1)</summary><blockquote> `334-346`: **Consider adding language identifier to code block.** The code block showing noop/stub exports (lines 334-346) lacks a language specifier. While this is a list of function names, adding a specifier (e.g., `text` or `typescript`) would suppress the linter warning. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text createGetChannelsMessage, parseGetChannelsResponse, ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-sdk-v1/reference.mdaround lines 334 - 346, The fenced
code block that lists stub exports such as createGetChannelsMessage,
parseGetChannelsResponse, createGetLedgerBalancesMessage,
parseGetLedgerEntriesResponse, createTransferMessage,
createCreateChannelMessage, convertRPCToClientChannel, parseAnyRPCResponse,
NitroliteRPC, etc., needs a language identifier to satisfy the linter; update
the block opener fromto a language-tagged fence liketext or
typescript so the block becomestext (ortypescript) ...thereby
suppressing the warning while leaving the content unchanged.</details> </blockquote></details> <details> <summary>docs/skills/yellow-session-keys/SKILL.md (1)</summary><blockquote> `26-35`: **Consider adding language identifier to lifecycle diagram.** The session key lifecycle diagram would benefit from a language specifier (e.g., `text`) to suppress linter warnings. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/skills/yellow-session-keys/SKILL.mdaround lines 26 - 35, The fenced
code block showing the session key lifecycle (the list starting with "Generate
session key (local) ──▶ (sessionKey.address, sessionKey.privKey)" through
"Revoke if compromised") is missing a language identifier; update the opening
fence to include a language specifier like "text" (e.g., replace "" with "text") so the linter stops complaining and the diagram is treated as plain
text.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@docs/skills/yellow-app-sessions/SKILL.md:
- Around line 26-36: The fenced diagram and other unlabeled code blocks (e.g.,
the create_app_session/state/close_app_session diagram and the blocks at the
indicated ranges) need language tags to satisfy markdownlint MD040; update each
fence to include an appropriate tag such as text for ASCII diagrams, json for
JSON examples, or ts for TypeScript snippets (e.g., changetotext for
the create_app_session diagram and apply similar text/json/ts labels to the
fences at 107-111, 175-179, 192-196, and 208-212).In
@docs/skills/yellow-clearnode-auth/SKILL.md:
- Around line 236-239: The helper return types currently use { jwt } but earlier
docs and server responses use jwt_token; update the three helper signatures
(authenticate, sendAuthRequest, sendAuthVerify) to consistently return or map to
jwt_token (e.g., Promise<{ jwt_token }> or explicitly document mapping from {
jwt } -> jwt_token) so the naming matches the server response and other doc
references.In
@docs/skills/yellow-errors/SKILL.md:
- Around line 145-146: Replace the outdated literal "Invalid signature" with the
canonical auth error string "invalid challenge or signature" in the guidance
entry and adjust the retry guidance to reference that exact canonical string so
matchers won't miss this branch; locate the list entry containing "Invalid
signature" and update the text to say that an "invalid challenge or signature"
indicates a signer/auth problem and retry won't help (must perform fresh auth).In
@docs/skills/yellow-network-builder/reference.md:
- Around line 54-66: The docs list environment variables (HTTP_PORT,
METRICS_PORT, DATABASE_DRIVER, MSG_EXPIRY_TIME) that the runtime does not read;
update docs/skills/yellow-network-builder/reference.md to either remove those
four vars or clearly mark them as unsupported/legacy, and add a short note
pointing operators to the actual runtime config entry points (e.g., the
clearnode main() startup config and the runtime initialization function such as
NewRuntime / LoadConfig in clearnode/runtime.go) so readers know where to find
supported knobs; ensure the table row entries for those four vars are deleted or
annotated and any example usages referring to them are updated.In
@docs/skills/yellow-network-builder/SKILL.md:
- Around line 56-67: The example uses object-style calls for client.deposit and
client.transfer but the actual SDK methods expect positional arguments; update
the example to call client.deposit with positional parameters (e.g.,
client.deposit(chainId, token, amount)) and client.transfer with positional
parameters (e.g., client.transfer(destination, allocations)); keep the rest
(Client.create, createSigners, PRIVATE_KEY, USDC, stateSigner, txSigner)
unchanged so the snippet matches the sdk/ts/src/client.ts signatures.In
@docs/skills/yellow-nitro-rpc/SKILL.md:
- Around line 128-142: The example Node.js one-liner uses require('ws') and
creates a WS instance (const WS = require('ws'); const ws = new WS(...)) but
does not tell users to install the dependency; update the SKILL.md "Quick sanity
test" section to add an explicit installation step instructing users to run npm
install ws (or mention adding "ws" to package.json) before running the one-liner
so the require('ws') call succeeds.In
@docs/skills/yellow-queries/reference.md:
- Around line 287-292: The example iterates over ledger_transactions but uses
incorrect field names (tx.sender/tx.receiver); update the render call to use the
schema-correct properties (tx.from_account and tx.to_account) so the loop uses
ledger_transactions' actual fields; locate the loop that references
ledger_transactions and replace tx.sender and tx.receiver with tx.from_account
and tx.to_account (leave tx.tx_type, tx.amount, tx.asset as-is).In
@docs/skills/yellow-state-channels/rules/state-channel-patterns.md:
- Around line 7-14: The fenced code blocks showing example state transitions
(e.g., "create(channel, stateWithSigs[0+1]) → ACTIVE ..." and "create(channel,
stateWithSig[0]) → INITIAL") must include a language label for MD040 compliance;
update each triple-backtick fence around those examples (and the other affected
blocks noted at ranges 20-29 and 81-87) to use an appropriate tag such as
text (orsolidity/```typescript if you prefer) so the markdown linter
passes and rendering is consistent.
Nitpick comments:
In@docs/skills/README.md:
- Line 3: Change the phrase "markdown document" to "Markdown document" in the
README sentence so the proper noun casing is used; update the sentence that
currently reads "Each skill is a focused markdown document with frontmatter..."
to "Each skill is a focused Markdown document with frontmatter..." to maintain
consistent capitalization in docs.In
@docs/skills/yellow-custody-contract/SKILL.md:
- Around line 157-164: The fenced code block showing the off-chain/on-chain
sequence (the lines beginning "off-chain create_channel (RPC) ─▶ ClearNode
returns channel + state0 + serverSig" through "on-chain
Custody.close(channelId, state, userSig, serverSig) (2 sigs)") is unlabeled
and triggers markdownlint MD040; add a language tag (e.g., change the opening
totext) to the fenced block in SKILL.md so the block is explicitly
marked and the lint warning is resolved.In
@docs/skills/yellow-deposits-withdrawals/SKILL.md:
- Around line 22-34: The ASCII diagram code block lacks a language identifier
which triggers linter warnings; update the opening fenced block fromto include a language specifier liketext (or ```mermaid if you convert the
diagram) so the diagram is treated correctly by the linter and markdown
renderer, ensuring the block around the lines containing "EOA / Smart Wallet",
"Custody contract", "Unified balance (off-chain)" etc. is updated accordingly.In
@docs/skills/yellow-nitro-rpc/SKILL.md:
- Around line 22-35: The fenced code block that shows the envelope format for
the Request/Response (the block containing the "req"/"res" JSON-like objects and
"sig" arrays) is missing a language identifier; update the opening fence from
to a language tag such asts or ```typescript so the snippet gets proper
TypeScript/JSON syntax highlighting (leave the block contents unchanged, only
add the language specifier).In
@docs/skills/yellow-sdk-api/reference.md:
- Around line 255-276: Add a short, explicit pointer in the v1 preview telling
readers to use docs/api.yaml as the canonical source for v1 RPC methods/types;
update the paragraph around the Client/createSigners example (and the sentence
that warns about dotted namespaces like channels.v1.get_home_channel,
user.v1.get_balances, node.v1.ping) to append a clear note such as “Canonical v1
RPC methods and schemas live in docs/api.yaml” so future edits reference
docs/api.yaml for method-name and type authority.In
@docs/skills/yellow-sdk-v1/reference.md:
- Around line 334-346: The fenced code block that lists stub exports such as
createGetChannelsMessage, parseGetChannelsResponse,
createGetLedgerBalancesMessage, parseGetLedgerEntriesResponse,
createTransferMessage, createCreateChannelMessage, convertRPCToClientChannel,
parseAnyRPCResponse, NitroliteRPC, etc., needs a language identifier to satisfy
the linter; update the block opener fromto a language-tagged fence liketext ortypescript so the block becomestext (ortypescript) ...
thereby suppressing the warning while leaving the content unchanged.In
@docs/skills/yellow-sdk-v1/SKILL.md:
- Around line 10-13: The source_urls list in SKILL.md is missing the canonical
v1 API reference; update the source_urls array to include "docs/api.yaml" so the
v1 skill points to the repository's canonical RPC/type schemas; modify the
source_urls entry in SKILL.md (the source_urls block) to add "docs/api.yaml"
alongside the existing npm and docs links to ensure v1 canonicality.In
@docs/skills/yellow-session-keys/SKILL.md:
- Around line 26-35: The fenced code block showing the session key lifecycle
(the list starting with "Generate session key (local) ──▶ (sessionKey.address,
sessionKey.privKey)" through "Revoke if compromised") is missing a language
identifier; update the opening fence to include a language specifier like "text"
(e.g., replace "" with "text") so the linter stops complaining and the
diagram is treated as plain text.In
@docs/skills/yellow-state-channels/reference.md:
- Around line 163-187: The fenced code block containing the step-by-step
challenge-response protocol (the triple-backtick block showing steps 1–3b) lacks
a language identifier which triggers linter warnings; add a language tag such as
text ormarkdown immediately after the opening backticks to suppress
warnings and clarify the block's format while leaving the block content
unchanged.- Around line 9-14: The code block containing the EIP-712 domain parameters (the
lines with keys name, version, chainId, verifyingContract) should include a
language identifier for proper rendering; update the opening triple-backticks to
include a language such as yaml (e.g., changetoyaml) so the block is
highlighted correctly in the docs.- Around line 41-43: The code block showing the channelId derivation lacks a
language identifier; update the fenced code block around "channelId =
keccak256(abi.encode(participants, adjudicator, challenge, nonce, chainId))" to
include an appropriate language tag (e.g.,solidityortext) so the
expression using keccak256 and abi.encode (and the variables participants,
adjudicator, challenge, nonce, chainId) renders with correct syntax
highlighting.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `6f3c650d-6592-420e-b09a-e41b0f978ac2` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 1b70c806b130bdffa188548c9832383b59565862 and 0a01fd3b40a1bfd2b2bfbbad864c71f21c73c89e. </details> <details> <summary>📒 Files selected for processing (24)</summary> * `docs/skills/README.md` * `docs/skills/yellow-app-sessions/SKILL.md` * `docs/skills/yellow-clearnode-auth/SKILL.md` * `docs/skills/yellow-custody-contract/SKILL.md` * `docs/skills/yellow-deposits-withdrawals/SKILL.md` * `docs/skills/yellow-errors/SKILL.md` * `docs/skills/yellow-network-builder/.claude-plugin/plugin.json` * `docs/skills/yellow-network-builder/SKILL.md` * `docs/skills/yellow-network-builder/reference.md` * `docs/skills/yellow-network-builder/rules/yellow-patterns.md` * `docs/skills/yellow-nitro-rpc/SKILL.md` * `docs/skills/yellow-notifications/SKILL.md` * `docs/skills/yellow-queries/SKILL.md` * `docs/skills/yellow-queries/reference.md` * `docs/skills/yellow-sdk-api/SKILL.md` * `docs/skills/yellow-sdk-api/reference.md` * `docs/skills/yellow-sdk-v1/SKILL.md` * `docs/skills/yellow-sdk-v1/reference.md` * `docs/skills/yellow-session-keys/SKILL.md` * `docs/skills/yellow-state-channels/.claude-plugin/plugin.json` * `docs/skills/yellow-state-channels/SKILL.md` * `docs/skills/yellow-state-channels/reference.md` * `docs/skills/yellow-state-channels/rules/state-channel-patterns.md` * `docs/skills/yellow-transfers/SKILL.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
…sion protocol field - New skill yellow-swap-design covers the three realistic patterns for off-chain asset exchange when the protocol has no native swap primitive (treasury-convert, market-maker agent, P2P matching), explains why routing through "Yellow brokers" or yellow.pro is not currently possible, and outlines what a v2 with real counterparty matching would need from the protocol team. - yellow-app-sessions: clarify that the `protocol` field is the NitroRPC protocol version (NitroRPC/0.4 / NitroRPC/0.2), NOT an app-type enum; the `application` field is free-form and there is no central registry. - yellow-network-builder: add a "brokers — clarifying a confusing term" section (ClearNode operators are called brokers but are not market makers) and a github.com/layer-3 repo map (nitrolite, docs, clearsync, broker-contracts, cosign-demo). Note that yellow.pro is a consumer UI, not callable backend infrastructure. - last_verified bumped to 2026-04-26 for the touched skills. Catalog README updated with the new skill.
Actionable fixes (8 verified against the actual SDK / runtime):
- yellow-network-builder/SKILL.md: client.deposit / client.transfer were
shown with object-literal args; the v1 Client class takes positional
args (blockchainId: bigint, asset: string, amount: Decimal). Verified
against package/dist/client.d.ts in @yellow-org/sdk@1.2.0.
- yellow-clearnode-auth/SKILL.md: helper return types now declare
Promise<{ jwt_token: string }> to match the canonical server response
field name (the surrounding doc text already flags `jwt` as a common
mistake — the helpers were the only place still using it).
- yellow-errors/SKILL.md: replace literal "Invalid signature" guidance
with the canonical "invalid challenge or signature" string from the
retry table so substring matchers stay in sync.
- yellow-network-builder/reference.md: drop HTTP_PORT, METRICS_PORT,
DATABASE_DRIVER, MSG_EXPIRY_TIME from the env-var table — clearnode
doesn't read these from the environment; they belong in the YAML
config under CLEARNODE_CONFIG_DIR_PATH. Added a short note pointing
operators at the right place.
- yellow-nitro-rpc/SKILL.md: prepend `npm install ws` to the sandbox
one-liner so the require('ws') call works on a fresh shell.
- yellow-queries/reference.md: ledger_transactions render example used
tx.sender / tx.receiver — schema is from_account / to_account; fixed.
- yellow-sdk-v1/SKILL.md: add docs/api.yaml as an explicit canonical
source URL so the v1 skill points at the schema file maintainers
recommend.
- README.md: "markdown" → "Markdown" (proper-noun casing).
Plus markdownlint MD040 — language tags added to ~20 unlabeled fenced
code blocks across the skill set (text/typescript as appropriate).
There was a problem hiding this comment.
Actionable comments posted: 9
♻️ Duplicate comments (1)
docs/skills/yellow-clearnode-auth/SKILL.md (1)
41-43:⚠️ Potential issue | 🟡 MinorFix JWT field name in the handshake diagram.
The diagram still shows
{ jwt }, but this document’s canonical response shape is{ jwt_token }. Keep the sequence diagram consistent with the rest of the spec text.Proposed fix
- │ { jwt } │ + │ { jwt_token } │🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/skills/yellow-clearnode-auth/SKILL.md` around lines 41 - 43, The handshake sequence diagram shows the response payload as "{ jwt }" but the canonical response field used elsewhere is "{ jwt_token }"; update the diagram to replace "jwt" with "jwt_token" so the sequence step labeled "response" returns "{ jwt_token }" and remains consistent with the rest of the spec.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/skills/yellow-deposits-withdrawals/SKILL.md`:
- Around line 166-169: Update the documented on-chain event signatures to match
the actual ChannelHub contract: replace the incorrect Deposited/Withdrawn
signatures that include an account parameter with the correct signatures that
only include token and amount (i.e., remove the account parameter and keep token
indexed), ensuring the reconciliation section's event ABI matches
ChannelHub.sol's event definitions Deposited and Withdrawn.
In `@docs/skills/yellow-errors/SKILL.md`:
- Around line 116-117: The conditional that checks auth-related messages uses
msg.startsWith('Authentication required') and misses the lowercase sandbox
output; update the matcher in the block that calls reAuthenticate() (the if that
inspects msg and invokes reAuthenticate()) to also match the canonical lowercase
form — either by normalizing msg (e.g., using msg.toLowerCase()) before
startsWith checks or by adding a second startsWith('authentication required')
branch so both "Authentication required" and "authentication required" trigger
reAuthenticate().
- Around line 31-33: Update the documentation in SKILL.md to correct the
semantics: do not state that the response's "method" is literally "error";
instead document that implementations preserve the original request "method" and
set the message "type" to "error" for error responses, and that the response
"result" contains a single string field named "error" (result.error); make this
change wherever the file currently asserts method="error" so routing/correlation
consumers read the correct behavior.
In `@docs/skills/yellow-network-builder/reference.md`:
- Around line 236-239: The code example uses the old array-style transfer
signature; update the call to use the v1 Client.transfer(recipientWallet:
string, asset: string, amount: Decimal) signature by calling client.transfer
with recipientAddress as the first arg, the asset string ('usdc') as the second,
and a Decimal instance for the amount (e.g., new Decimal(50)) as the third;
adjust imports/usage to ensure Decimal is available where client.transfer is
invoked.
- Around line 217-225: The example auth payload uses legacy field names; update
the payload fields to the v0.5.3+ canonical names: replace wallet with address,
sessionKeyAddress with session_key, appName with application, and expireSeconds
with expires_at; ensure expires_at is expressed in milliseconds (multiply
seconds by 1000) and keep the note that the payload is signed with the main
wallet via EIP-712 so examples like the commented allowances and signing
description remain consistent.
In `@docs/skills/yellow-queries/reference.md`:
- Around line 14-27: The table and examples list unversioned RPC method names
(e.g., ping, get_config, get_channels, get_app_definition, get_ledger_entries,
get_ledger_balances, get_user_tag, get_session_keys, get_rpc_history); update
them to the canonical, versioned RPC names (for example node.v1.ping,
node.v1.get_config, assets.v1.get_assets, apps.v1.get_app_definition,
channels.v1.get_channels, sessions.v1.get_app_sessions,
ledger.v1.get_ledger_entries, ledger.v1.get_ledger_transactions,
ledger.v1.get_ledger_balances, users.v1.get_user_tag,
sessions.v1.get_session_keys, rpc.v1.get_rpc_history) wherever those method
names appear in the index table and the example snippets (also update the
similar occurrences around the later block referenced in the comment). Ensure
consistency across the document so examples will call the versioned methods that
the server expects.
In `@docs/skills/yellow-sdk-v1/reference.md`:
- Around line 68-75: The exported options list is missing withApplicationID;
update the "Exported Option factories (verified)" section to include
`withApplicationID(applicationId: string)` alongside `withHandshakeTimeout`,
`withErrorHandler`, and `withBlockchainRPC`, and ensure the surrounding note
about `withPingInterval` remains unchanged so documentation matches the actual
exports from the SDK (refer to the export symbol `withApplicationID` in the
package source).
- Around line 226-236: Remove the incorrect AppSessionsV1CloseAppSessionMethod
entry from the app_sessions.v1 method list in the docs (the list that currently
includes AppSessionsV1CloseAppSessionMethod) so it matches the canonical v1 RPC
API; update any surrounding text if it references closing sessions to instead
mention using SubmitAppState (SubmitAppState /
AppSessionsV1SubmitAppStateMethod) with a Close intent as the supported way to
close an app session.
In `@docs/skills/yellow-swap-design/SKILL.md`:
- Around line 128-153: The example uses non-existent helpers
sendCreateAppSession and sendCloseAppSession; replace the creation call with the
SDK method appSessionsV1CreateAppSession passing the same payload (definition,
allocations, nonce, participants) and use submitAppState to close the session by
submitting a state with intent set to Close (include app_session_id, the final
allocations array, and any required signatures via signer/requestSigner). Ensure
you pass the original fields (definition, allocations, app_session_id) to
appSessionsV1CreateAppSession and construct the Close intent payload for
submitAppState so the final state mirrors the allocations shown.
---
Duplicate comments:
In `@docs/skills/yellow-clearnode-auth/SKILL.md`:
- Around line 41-43: The handshake sequence diagram shows the response payload
as "{ jwt }" but the canonical response field used elsewhere is "{ jwt_token }";
update the diagram to replace "jwt" with "jwt_token" so the sequence step
labeled "response" returns "{ jwt_token }" and remains consistent with the rest
of the spec.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a566bf9b-178e-49e8-ad79-c06141c046a5
📒 Files selected for processing (17)
docs/skills/README.mddocs/skills/yellow-app-sessions/SKILL.mddocs/skills/yellow-clearnode-auth/SKILL.mddocs/skills/yellow-custody-contract/SKILL.mddocs/skills/yellow-deposits-withdrawals/SKILL.mddocs/skills/yellow-errors/SKILL.mddocs/skills/yellow-network-builder/SKILL.mddocs/skills/yellow-network-builder/reference.mddocs/skills/yellow-nitro-rpc/SKILL.mddocs/skills/yellow-queries/reference.mddocs/skills/yellow-sdk-v1/SKILL.mddocs/skills/yellow-sdk-v1/reference.mddocs/skills/yellow-session-keys/SKILL.mddocs/skills/yellow-state-channels/SKILL.mddocs/skills/yellow-state-channels/reference.mddocs/skills/yellow-state-channels/rules/state-channel-patterns.mddocs/skills/yellow-swap-design/SKILL.md
✅ Files skipped from review due to trivial changes (9)
- docs/skills/README.md
- docs/skills/yellow-state-channels/SKILL.md
- docs/skills/yellow-custody-contract/SKILL.md
- docs/skills/yellow-nitro-rpc/SKILL.md
- docs/skills/yellow-session-keys/SKILL.md
- docs/skills/yellow-state-channels/reference.md
- docs/skills/yellow-app-sessions/SKILL.md
- docs/skills/yellow-state-channels/rules/state-channel-patterns.md
- docs/skills/yellow-network-builder/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/skills/yellow-sdk-v1/SKILL.md
| Rules: | ||
| - The response's **method is literally `"error"`**, not the request method. | ||
| - The result object has a single `error` string field. |
There was a problem hiding this comment.
Correct method-vs-type semantics in error responses.
This section says the response method is "error", but implementation-level behavior preserves the original request method and marks the message type as error. This distinction matters for request routing/correlation logic.
Proposed doc correction
-Rules:
-- The response's **method is literally `"error"`**, not the request method.
-- The result object has a single `error` string field.
+Rules:
+- The response message **type** is `"error"` (error response), while method correlation remains tied to the original request method.
+- The result object has a single `error` string field.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/skills/yellow-errors/SKILL.md` around lines 31 - 33, Update the
documentation in SKILL.md to correct the semantics: do not state that the
response's "method" is literally "error"; instead document that implementations
preserve the original request "method" and set the message "type" to "error" for
error responses, and that the response "result" contains a single string field
named "error" (result.error); make this change wherever the file currently
asserts method="error" so routing/correlation consumers read the correct
behavior.
…+ ChannelHub.sol
Eight more findings, every one verified:
- yellow-clearnode-auth: handshake diagram still showed `{ jwt }` —
fixed to `{ jwt_token }` to match the rest of the spec.
- yellow-deposits-withdrawals: Deposited / Withdrawn event signatures
drop the bogus `account indexed` parameter. Verified against
contracts/src/ChannelHub.sol:62-65 — events are
`(address indexed token, uint256 amount)`. Added a note that the
account is `msg.sender`, attributable from the transaction log.
- yellow-errors: retry matcher normalises with toLowerCase() so both
"Authentication required" and the canonical lowercase
"authentication required" trigger reAuthenticate().
- yellow-network-builder/reference.md (auth payload): legacy field
names → canonical (address / session_key / application / expires_at
in milliseconds). Verified against yellow-clearnode-auth which is
itself the canonical source.
- yellow-network-builder/reference.md (transfer): array signature →
positional (recipient, asset, Decimal). Verified against v1 Client
type definitions.
- yellow-queries: methods now show v0.5.3 unversioned wire names AND
the canonical v1 namespaced names side-by-side. Verified against
docs/api.yaml — v1 uses `node.v1.ping`, `channels.v1.get_channels`,
`app_sessions.v1.get_app_sessions`, etc.
- yellow-sdk-v1/reference: added `withApplicationID(applicationId)` to
the verified Option factory list (it's exported from
sdk/ts/src/index.ts:27 alongside the other three). Removed
`AppSessionsV1CloseAppSessionMethod` — verified absent from
docs/api.yaml; closing in v1 happens via SubmitAppState with
intent='close'.
- yellow-swap-design: example helpers `sendCreateAppSession` /
`sendCloseAppSession` were placeholders that don't exist in the v1
SDK; replaced with `appSessionsV1CreateAppSession` for creation and
`submitAppState` with `intent: 'close'` for closing.
philanton
left a comment
philanton
left a comment
There was a problem hiding this comment.
Overall: skill set documents 0.5.x compat surface as canonical v1 protocol
Repo CLAUDE.md is explicit: v1 lives at docs/api.yaml + sdk/ts/src/rpc/methods.ts with grouped names like channels.v1.submit_state, app_sessions.v1.create_app_session. Legacy 0.5.x compat names (auth_request, transfer, create_channel, flat submit_app_state, bu/cu/tr/asu push notifications) live only in sdk/ts-compat/ and are not the protocol.
Scope policy: only v1-relevant content for this repo
We are not interested in landing skills whose content is not relevant to v1 of the Nitrolite protocol and to this repo. Skills should describe v1 (per docs/api.yaml, sdk/ts/src/rpc/methods.ts, contracts/src/ChannelHub.sol), not the deprecated 0.5.x compat surface that lives in sdk/ts-compat/. References to entities that don't exist in this monorepo at all — NodeRegistry, AppRegistry, SimpleConsensus, Remittance adjudicators, Custody.sol — should be dropped or moved out. contracts/src/ only ships ChannelHub.sol, ChannelEngine.sol, EscrowDepositEngine.sol, EscrowWithdrawalEngine.sol, Utils.sol, WadMath.sol, PremintERC20.sol, plus interfaces/ and sigValidators/. If something exists only in another codebase, link out — don't fabricate it as part of Nitrolite.
Skills to drop or rewrite from scratch (frontmatter pins @erc7824/nitrolite@^0.5.3)
yellow-clearnode-auth—auth_request/auth_challenge/auth_verifynot in v1; auth is internal toClient.create().yellow-app-sessions— flatcreate_app_session/submit_app_state/close_app_session. v1 names areapp_sessions.v1.*andclose_app_sessiondoes not exist.yellow-queries(skill +reference.md) — invents v1 namespaces (assets.v1,apps.v1,ledger.v1,users.v1,sessions.v1,rpc.v1) that don't exist; lists 12 query methods, most of which have no v1 equivalent.yellow-notifications—bu/cu/tr/asupush events don't exist in v1.yellow-errors—auth_requesterror rows are compat-layer strings.yellow-sdk-api— recommendsnpm install @erc7824/nitrolite(package not in this monorepo).yellow-transfers—transferRPC method doesn't exist in v1.yellow-session-keys—revoke_session_keyRPC method doesn't exist in v1.yellow-custody-contract— entire skill describesCustody.solwhich doesn't exist; v1 entrypoint isChannelHub.sol.yellow-deposits-withdrawals— every flow keyed on Custody contract.yellow-state-channels(skill +reference.md+rules/) —Custody.create/resize/close,VirtualApp:CustodyEIP-712 domain,NodeRegistry,AppRegistry,SimpleConsensus,Remittance— none of these match v1 SOT.yellow-nitro-rpc— wire format claimsauth_request/create_app_session/transferare canonical method names;bu/cu/tr/asulisted as v1 notifications. Verify entire envelope againstsdk/ts/src/rpc/message.tsif salvageable.
If the goal is documenting the 0.5.x compat layer for migration purposes, that's fine — but it should live elsewhere (docs/skills/legacy/, network: legacy-0.5.x frontmatter, point at @yellow-org/sdk-compat), not be presented as the canonical Nitrolite protocol surface.
README.md (catalog)
The catalog at docs/skills/README.md lists every skill above and references @erc7824/nitrolite v0.5.x (frozen) (line 36), auth_request → auth_challenge → auth_verify (line 18), bu/cu/tr/asu push notifications (line 21), and a fabricated 8011 stale error code (line 7 — no numeric error codes exist in nitronode//pkg//sdk/; yellow-errors itself notes the protocol uses descriptive strings only). Catalog needs full rewrite once dropped skills are removed. Also: README.md:51 mentions YellowHive — PR description claims "0 hits" for that grep. Same for yellow-swap-design/SKILL.md:66. Either scrub or correct the claim.
Cross-cutting issues
- Wrong package name: 12 SKILL.md frontmatters declare
sdk_version: "@erc7824/nitrolite@^0.5.3". Repo only ships@yellow-org/sdk@1.2.0and@yellow-org/sdk-compat@1.2.0. - Wrong contract name: every
Custody contract/VirtualApp:Custodyreference. v1 isChannelHub.sol. last_verified: 2026-04-26is misleading across 16 frontmatters — none of the above was cross-checked against v1 SOT.- Off-by-one: PR description says 14 skills, diff has 15 (
yellow-swap-designis in catalog but not the PR table). - Frontmatter shape drift:
yellow-swap-designlackssdk_version/user-invocable;yellow-custody-contractcarries an extracontract_versionfield.
Path forward
For the v1-relevant skills (yellow-network-builder + companions, yellow-sdk-v1 + companions, yellow-swap-design), see inline comments. Either rewrite against v1 SOT or pull and re-submit per skill once verified.
| **Protocol**: NitroRPC/0.4 (wire) + VirtualApp:Custody v0.3.0 (on-chain) | ||
| **Active SDK**: `@yellow-org/sdk@^1.2.0` (legacy: `@erc7824/nitrolite@^0.5.3`, frozen) |
There was a problem hiding this comment.
VirtualApp:Custody v0.3.0 and legacy: @erc7824/nitrolite@^0.5.3, frozen should both go. v1 entrypoint is contracts/src/ChannelHub.sol. The legacy bullet recommends a package not in this monorepo — drop it or repoint at @yellow-org/sdk-compat@^1.2.0 if a migration path is needed.
| **Protocol**: NitroRPC/0.4 (wire) + VirtualApp:Custody v0.3.0 (on-chain) | |
| **Active SDK**: `@yellow-org/sdk@^1.2.0` (legacy: `@erc7824/nitrolite@^0.5.3`, frozen) | |
| **Protocol**: Nitro RPC v1 (wire) + ChannelHub (on-chain) | |
| **Active SDK**: `@yellow-org/sdk@^1.2.0` |
| settlement across EVM chains. Lock funds on-chain once; transact unlimited | ||
| times off-chain via signed state updates; settle on-chain once. Finality | ||
| < 1 second, zero gas per operation, funds always recoverable via the | ||
| Custody contract. |
There was a problem hiding this comment.
Replace every Custody contract with ChannelHub contract. Same applies at line 61 (Custody + Adjudicator contracts). No Custody.sol in contracts/src/ of this repo.
| - `yellow-notifications` — `bu`/`cu`/`tr`/`asu` server-push | ||
|
|
||
| **On-chain** | ||
| - `yellow-custody-contract` — Solidity ABI, events, structs | ||
|
|
||
| **SDKs** | ||
| - `yellow-sdk-v1` — `@yellow-org/sdk@1.x` (**active**) | ||
| - `yellow-sdk-api` — legacy `@erc7824/nitrolite@0.5.3` (frozen) |
There was a problem hiding this comment.
Line 118: bu/cu/tr/asu server-push references. v1 has no such notifications (sdk/ts/src/rpc/api.ts only defines ChannelsV1HomeChannelCreatedEvent); v1 replaces push with polling. Line 125: yellow-sdk-api — legacy @erc7824/nitrolite@0.5.3 (frozen) — package not in monorepo. Both bullets should be removed if those sibling skills are dropped per scope policy (see top-level body).
| **Status**: Production Ready | ||
| **Version**: 3.0.0 | ||
| **Last Verified**: 2026-04-23 | ||
| **Dependencies**: `@yellow-org/sdk@^1.2.0` (active) or `@erc7824/nitrolite@^0.5.3` (legacy/frozen), `viem` |
There was a problem hiding this comment.
Drop the @erc7824/nitrolite@^0.5.3 (legacy/frozen) arm — package not in this monorepo.
| **Dependencies**: `@yellow-org/sdk@^1.2.0` (active) or `@erc7824/nitrolite@^0.5.3` (legacy/frozen), `viem` | |
| **Dependencies**: `@yellow-org/sdk@^1.2.0`, `viem` |
| **Version**: 3.0.0 | ||
| **Last Verified**: 2026-04-23 | ||
| **Dependencies**: `@yellow-org/sdk@^1.2.0` (active) or `@erc7824/nitrolite@^0.5.3` (legacy/frozen), `viem` | ||
| **Protocol**: NitroRPC/0.4 (spec) + VirtualApp:Custody v0.3.0 (on-chain) |
There was a problem hiding this comment.
NitroRPC/0.4 (spec) + VirtualApp:Custody v0.3.0 (on-chain) doesn't match v1. v1 entrypoint is ChannelHub.
| **Protocol**: NitroRPC/0.4 (spec) + VirtualApp:Custody v0.3.0 (on-chain) | |
| **Protocol**: Nitro RPC v1 (spec) + ChannelHub (on-chain) |
| | Namespace | Example methods | | ||
| |---|---| | ||
| | `channels.v1.*` | `get_home_channel`, `request_creation`, `submit_state` | | ||
| | `app_sessions.v1.*` | `submit_deposit_state`, `submit_session_key_state` | |
There was a problem hiding this comment.
app_sessions.v1.* row only lists submit_deposit_state and submit_session_key_state — missing the most-used methods. Real exports from sdk/ts/src/rpc/methods.ts: create_app_session, submit_app_state, submit_deposit_state, submit_session_key_state, rebalance_app_sessions, get_app_definition, get_app_sessions, get_last_key_states. Pick the three highest-leverage ones for the example column.
| | `app_sessions.v1.*` | `submit_deposit_state`, `submit_session_key_state` | | |
| | `app_sessions.v1.*` | `create_app_session`, `submit_app_state`, `get_app_sessions` | |
| yourself, or answering "can I just plug into the Yellow swap API?" | ||
| version: 1.0.0 | ||
| network: mainnet | ||
| last_verified: 2026-04-26 |
There was a problem hiding this comment.
Frontmatter lacks sdk_version and user-invocable that other skills carry. README claims uniform schema. Pick a shape and apply consistently.
| last_verified: 2026-04-26 | |
| last_verified: 2026-04-26 | |
| sdk_version: "@yellow-org/sdk@^1.2.0" | |
| user-invocable: true |
| - **When OK:** v1 / closed beta / capped per-user, per-day amounts. | ||
| Label it honestly ("Treasury Convert" / "v1") so users understand the | ||
| model and the caps. | ||
| - **Reference impl:** YellowHive `SwapService.executeSwap` is exactly this |
There was a problem hiding this comment.
PR description claims 0 YellowHive hits. This line says **Reference impl:** YellowHive SwapService.executeSwap. Either drop the line or correct the PR description. Plus: per scope policy, the protocol-generic doc shouldn't reference an external implementation by name.
|
|
||
| The v1 SDK uses `appSessionsV1CreateAppSession` to open the session and | ||
| `submitAppState` with `intent: 'close'` to close — there's no dedicated | ||
| `close_app_session` method in v1 (see `yellow-sdk-v1` reference). The |
There was a problem hiding this comment.
This file correctly notes "no close_app_session method in v1". Other skills in this PR (e.g. yellow-app-sessions/SKILL.md:4) treat close_app_session as a real method. Resolve consistently across the set — single source of truth on close semantics. Keep this file's stance; fix the others (or drop them per scope policy).
| @@ -0,0 +1,10 @@ | |||
| { | |||
There was a problem hiding this comment.
Only 2 of 14 skills ship .claude-plugin/plugin.json (this one + yellow-state-channels). PR doesn't explain. Either every skill carries one (each independently installable as a plugin) or none do (catalog ships as a single bundle). Both extant files credit "YellowNetwork Builder Team" — not the PR author or any documented Yellow team. Verify provenance and pick one approach.
|
Thanks, agreed. I mixed too much 0.5.x/compat material into what should be v1-only Nitrolite docs. |
nksazonov
left a comment
nksazonov
left a comment
There was a problem hiding this comment.
Good direction! Still, this misses the golang sdk.
| | Off-chain | Clearnode WebSocket JSON-RPC | Fast state negotiation and reads | | ||
| | On-chain | `ChannelHub`, engines, validators | Deposits, checkpoints, challenges, closes | | ||
|
|
||
| The normal app path is: create a `Client`, produce off-chain states with high-level SDK methods, and submit on-chain checkpoints or challenges only when settlement or recovery is needed. |
There was a problem hiding this comment.
| The normal app path is: create a `Client`, produce off-chain states with high-level SDK methods, and submit on-chain checkpoints or challenges only when settlement or recovery is needed. | |
| The normal app path is: create a `Client`, produce off-chain states with high-level SDK methods, and submit on-chain deposit, withdrawals, checkpoints or challenges only when settlement or recovery is needed. |
| |---|---|---| | ||
| | Application | Your app and `@yellow-org/sdk` client | Product logic and UX | | ||
| | Off-chain | Clearnode WebSocket JSON-RPC | Fast state negotiation and reads | | ||
| | On-chain | `ChannelHub`, engines, validators | Deposits, checkpoints, challenges, closes | |
There was a problem hiding this comment.
| | On-chain | `ChannelHub`, engines, validators | Deposits, checkpoints, challenges, closes | | |
| | On-chain | `ChannelHub`, engines, validators | Deposits, withdrawals, checkpoints, challenges, closes | |
| source_urls: | ||
| - https://github.com/layer-3/nitrolite/blob/main/docs/api.yaml | ||
| - https://github.com/layer-3/nitrolite/blob/main/sdk/ts/src/rpc/methods.ts | ||
| - https://github.com/layer-3/nitrolite/blob/main/contracts/src/ChannelHub.sol |
There was a problem hiding this comment.
Generally, golang sdk is missing here. It is an alternative to the TS SDK for builders.
| | `sdk/ts` | Active TypeScript SDK package, published as `@yellow-org/sdk` | | ||
| | `sdk/ts-compat` | Compatibility package for older API shapes; not the v1 source of truth | |
There was a problem hiding this comment.
sdk/go is missing here as well.
4 participants
Summary
Adds 14 protocol-generic Claude Code skills under a new
docs/skills/tree, plus a catalog README. These are reference docs for builders integrating with Yellow Network — Nitro RPC wire format, ClearNode auth handshake, session keys, transfers, app sessions, channels, the Custody contract, both SDK versions, and a getting-started index that points at the rest.Provenance
They originated in YellowHive, an agent platform built on Yellow Network. Sharing them upstream so any builder on the protocol can use them — the project's own platform-specific skills (e.g., MCP HTTP integration with YellowHive's API) are kept downstream and not part of this PR.
Why
docs/skills/(not.claude/skills/)Existing
.claude/skills/is dev-workflow skills for repo contributors (build-sdk, lint, review-pr, test, typecheck). These are different in purpose — protocol references for external builders — so I placed them underdocs/skills/to keep the two intents cleanly separated. The catalogdocs/skills/README.mdmakes this distinction explicit. Happy to move them if you prefer a different layout.What's in the set
yellow-network-builderyellow-nitro-rpc,yellow-clearnode-auth,yellow-session-keys,yellow-queries,yellow-notifications,yellow-errorsyellow-deposits-withdrawals,yellow-transfers,yellow-state-channels,yellow-app-sessions,yellow-custody-contractyellow-sdk-v1(@yellow-org/sdk^1.x),yellow-sdk-api(@erc7824/nitrolite0.5.x, frozen)Each
SKILL.mdcarries frontmatter withversion,sdk_version,network, andlast_verified: 2026-04-26. Most include areference.mdwith extended detail and some haverules/*.mdwith patterns.Verification
grep -ric "yellowhive\|api-hive\|hive.seselo" docs/skills→ 0 hits across all 14 skills (confirmed protocol-generic).last_verifieddates bumped to 2026-04-26.yellow-nitro-rpc→yellow-clearnode-auth) preserved by relative[name](../name/SKILL.md)paths.Test plan
docs/skills/is the right home (vs.claude/skills/or another path).README.mdlink todocs/skills/README.md.🤖 Generated with Claude Code
Summary by CodeRabbit