Skip to content

feat: upd skills#437

Draft
skywardboundd wants to merge 3 commits into
ton-org:mainfrom
skywardboundd:skills-1
Draft

feat: upd skills#437
skywardboundd wants to merge 3 commits into
ton-org:mainfrom
skywardboundd:skills-1

Conversation

@skywardboundd

@skywardboundd skywardboundd commented May 28, 2026

Copy link
Copy Markdown

Summary by CodeRabbit

  • Documentation
    • Reorganized developer and contributor guides into a consolidated "kit-dev" workflow.
    • Removed older per-skill how-tos and replaced them with a unified set of recipes and development guidelines.
    • Added comprehensive AppKit consumer guides covering setup, hooks, streaming, transactions, and common gotchas.
    • Added evaluation suites and recipe templates to standardize actions/queries/hooks and testing expectations.
    • Updated contribution rules and styling/filename conventions.

@vercel

vercel Bot commented May 28, 2026

Copy link
Copy Markdown

@skywardboundd is attempting to deploy a commit to the TOP Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Jun 2, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 89631536-befa-4831-95bd-76e23ec57b1a

📥 Commits

Reviewing files that changed from the base of the PR and between 7d38284 and 4df30c2.

📒 Files selected for processing (5)
  • .claude/skills/kit-dev/SKILL.md
  • .claude/skills/kit-dev/evals.json
  • .claude/skills/kit-dev/skill-reference/recipes.md
  • packages/appkit/skills/ton-appkit/SKILL.md
  • packages/appkit/skills/ton-appkit/evals.json
✅ Files skipped from review due to trivial changes (4)
  • .claude/skills/kit-dev/evals.json
  • packages/appkit/skills/ton-appkit/SKILL.md
  • .claude/skills/kit-dev/skill-reference/recipes.md
  • .claude/skills/kit-dev/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • packages/appkit/skills/ton-appkit/evals.json

📝 Walkthrough

Walkthrough

This PR restructures documentation and development guidance by introducing two comprehensive skills: kit-dev for internal monorepo contributors (architecture, conventions, templates, testing) and ton-appkit for external library consumers (setup, API reference, recipes). The deprecated add-action-and-hook and add-ui-component skills are superseded, and contribution guides are updated to reference the new skills.

Changes

Kit-Dev Skill for Internal Monorepo Development

Layer / File(s) Summary
Core Architecture and Conventions
.claude/skills/kit-dev/SKILL.md (sections 1-4, 6-21, 38-52, 53-71, 72-91, 92-100)
Establishes monorepo three-layer structure (walletkit/appkit/appkit-react), documents walletkit import boundaries via appkit domain barrels, maps feature domains to action/hook directories, defines TanStack Query key prefixes for cache operations, and clarifies layer responsibilities.
Development Patterns and Debugging
.claude/skills/kit-dev/SKILL.md (sections 22-37, 101-131)
Documents task routing for implementing features, Vitest testing setup with wrapper/provider patterns and mocking guidance, and a comprehensive gotchas checklist covering cache invalidation, streaming provider per-network opt-in, BigInt serialization, SSR/provider requirements, and transaction error classification.
Evaluation Criteria
.claude/skills/kit-dev/evals.json
Defines evaluation suite with prompts and structured assertions covering action/query/hook naming conventions, directory targets, barrel exports, test requirements with mocking patterns, UI component constraints in appkit-react, and debugging scenarios.
Action/Query/Hook Templates
.claude/skills/kit-dev/skill-reference/recipes.md
Provides step-by-step templates for get-actions, watch-actions via appKit.emitter, query wiring with TanStack Query, React hooks, two watch patterns (useSyncExternalStore snapshot vs useEffect+invalidation), example locations with SAMPLE_START/SAMPLE_END markers, and completion checklist with export/test/docs requirements.

Ton-AppKit Skill for Library Consumer Integration

Layer / File(s) Summary
Setup and Package Overview
packages/appkit/skills/ton-appkit/SKILL.md (sections 1-5, 6-41, 42-48, 48-88, 90-112)
Distinguishes contributor vs consumer guidance, provides quick initialization example with required provider order (QueryClientProvider wrapping AppKitProvider), documents TonConnect connector/network configuration, Next.js SSR boundary behavior, and Vite/manual polyfill guidance for Node globals.
Hook Reference and Component API
packages/appkit/skills/ton-appkit/SKILL.md (sections 113-121, 122-187, 188-206, 207-220, 221-320, 321-342, 343-360)
Comprehensive reference for wallet connection, asset/balance, sending (TON/jettons/NFTs), signing, networking, and DeFi hooks; emphasizes pre-formatted decimal balances and human-readable string amounts; documents drop-in components, TanStack Query invalidation patterns, four critical patterns (streaming dual requirement, explicit cache updates post-mutation, transaction acceptance vs confirmation, error/retry handling), no-wallet fallback by platform, and extensive gotchas (provider order, formatting rules, streaming opt-in, network mismatch, iOS synchronous click, Telegram return strategy, tonstakers polling, SwapWidget silent errors).
Evaluation Criteria
packages/appkit/skills/ton-appkit/evals.json
Comprehensive evaluation suite with test cases covering setup, streaming balance/transactions, sending operations, swap/staking flows, cache cleanup, SSR, error handling/retry, connector UX, Telegram behavior, manifest troubleshooting, and data-shape expectations.
Extended Recipes
packages/appkit/skills/ton-appkit/skill-reference/recipes.md
Practical recipes for swap flows (drop-in widget + custom hook-based form), staking (provider selection, quote, build/send, unstake modes), jetton/NFT transfer with cache invalidation, transaction watching with onChange handler, multi-network app initialization with per-network clients, and custom mutation cleanup patterns.

Contribution Guide Updates and Skill Migration

Layer / File(s) Summary
Root and Package-Level Updates
CLAUDE.md, packages/appkit-react/CLAUDE.md, packages/appkit/CLAUDE.md
Adds agent skills discovery section to root CLAUDE.md pointing to kit-dev and ton-appkit skills; updates appkit-react and appkit CLAUDE.md to reference kit-dev instead of deprecated add-action-and-hook and add-ui-component skills; narrows styling guidance in appkit-react to use --ta-* design tokens (colors, border-radius, border-width) with literal px for spacing; adds kebab-case file naming convention requirement to appkit.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 New paths light the monorepo's way,
Kit-dev guides contributors through the day,
While ton-appkit welcomes consumers near,
With templates, patterns, recipes clear,
Skills restructured, confusion cleared! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'feat: upd skills' is vague and uses a non-descriptive abbreviation ('upd') that does not clearly convey what changes were made or their scope. Consider using a more descriptive title such as 'feat: consolidate development skills documentation' or 'feat: replace component/action skills with unified kit-dev guide' to better communicate the changeset's primary purpose.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@skywardboundd skywardboundd marked this pull request as ready for review June 11, 2026 22:00

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (3)
packages/appkit/skills/ton-appkit/evals.json (2)

34-41: 💤 Low value

Consider expanding jetton-send eval coverage.

Eval 3 currently has only 2 assertions, while similar mutation-based evals (e.g., eval 7 error-handling, eval 24 nft-transfer) have 4-5. Common jetton-send pitfalls that could be validated:

  • amount passed as human-readable string (not raw units or bigint)
  • isPending used to disable the send button
  • error/isError handling in the UI
  • recipientAddress format validation

The existing assertions cover the core hook + cache pattern, so this is optional — the missing patterns are tested in other evals (18, 21, 28, 38).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/appkit/skills/ton-appkit/evals.json` around lines 34 - 41, The
jetton-send eval ("id": 3, "name": "jetton-send") currently has only two
assertions; add extra assertions to validate common mutation UI and input
pitfalls: include an assertion checking that amount is passed as a
human-readable string (e.g., "amount_is_human_readable"), one that verifies the
send button is disabled when the mutation is pending (e.g.,
"uses_isPending_to_disable_send"), one for error handling in the UI (e.g.,
"shows_error_on_failure" or "handles_isError"), and one for recipient address
validation (e.g., "validates_recipient_address_format"); update the "assertions"
array in the eval definition to include these new assertion objects with brief
"description" fields mirroring the examples above.

84-84: Missing eval ID 8 in packages/appkit/skills/ton-appkit/evals.json

Eval IDs jump from 7 to 9 (skipping 8) around the reported line, and "id": 8 doesn’t appear anywhere else under packages/appkit/skills/. If IDs are intended to be contiguous, re-add/renumber the entry; otherwise document the intentional skip.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/appkit/skills/ton-appkit/evals.json` at line 84, The eval list in
evals.json jumps from "id": 7 to "id": 9, so add or restore an entry with "id":
8 (or renumber subsequent entries to be contiguous) so IDs are sequential;
locate the array entries around "id": 7 and "id": 9 in
packages/appkit/skills/ton-appkit/evals.json and either insert the missing eval
object with "id": 8 (populated like the nearby entries) or update "id" values
from 9 onward to close the gap, and if the skip is intentional, add a
comment/documentation in the file explaining the deliberate omission.
packages/appkit/skills/ton-appkit/SKILL.md (1)

1-4: ⚡ Quick win

Confirm SKILL.md is exempt from the kebab-case rule.

packages/appkit/**/* is supposed to use kebab-case filenames, and this entrypoint is the one exception here. If the loader doesn't require this exact casing, rename it before merge.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/appkit/skills/ton-appkit/SKILL.md` around lines 1 - 4, This SKILL.md
file is the intended exception to the packages/appkit/**/* kebab-case filename
rule; verify the build/loader that enforces kebab-case accepts this exact
filename (SKILL.md) for the ton-appkit entrypoint, and if it does not, either
update the loader/config to whitelist SKILL.md as an exception or rename the
file to a kebab-case alternative and update any imports/references to that
symbol; ensure the chosen fix is applied consistently so the bundler/loader no
longer fails on the ton-appkit entrypoint.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/kit-dev/skill-reference/recipes.md:
- Around line 28-71: The watch template must accept and forward resource
options: change watchXxx signature to accept parameters that extend
GetXxxOptions (e.g., { ...GetXxxOptions, onChange, onError? }), pass those
options into getXxx(appKit, options) when refreshing, and mark
cancelled/unsubscribe as before; also update Pattern B hook invalidation to
compute/invalidate using getXxxQueryKey(options) (or call handleXxxUpdate with
the same options) so the query key remains scoped to the resource inputs instead
of being global. Ensure you reference the existing types GetXxxReturnType and
GetXxxOptions (or create them if missing) and update any unsubscribe logic
(unsubscribeA/unsubscribeB) unchanged.

In `@packages/appkit/skills/ton-appkit/SKILL.md`:
- Line 34: Update the Next.js hydration guidance in SKILL.md by removing the
unsupported "ssr: true" hint and leaving the mount-gate / dynamic-import pattern
only; specifically, edit the table row that currently reads "'use client'
providers + `ssr: true` + mount gate or dynamic import" to drop the `ssr: true`
fragment and ensure any mention of AppKitConfig does not imply an `ssr` option,
keeping the advice focused on using mount gates or dynamic imports for
client-only providers.

---

Nitpick comments:
In `@packages/appkit/skills/ton-appkit/evals.json`:
- Around line 34-41: The jetton-send eval ("id": 3, "name": "jetton-send")
currently has only two assertions; add extra assertions to validate common
mutation UI and input pitfalls: include an assertion checking that amount is
passed as a human-readable string (e.g., "amount_is_human_readable"), one that
verifies the send button is disabled when the mutation is pending (e.g.,
"uses_isPending_to_disable_send"), one for error handling in the UI (e.g.,
"shows_error_on_failure" or "handles_isError"), and one for recipient address
validation (e.g., "validates_recipient_address_format"); update the "assertions"
array in the eval definition to include these new assertion objects with brief
"description" fields mirroring the examples above.
- Line 84: The eval list in evals.json jumps from "id": 7 to "id": 9, so add or
restore an entry with "id": 8 (or renumber subsequent entries to be contiguous)
so IDs are sequential; locate the array entries around "id": 7 and "id": 9 in
packages/appkit/skills/ton-appkit/evals.json and either insert the missing eval
object with "id": 8 (populated like the nearby entries) or update "id" values
from 9 onward to close the gap, and if the skip is intentional, add a
comment/documentation in the file explaining the deliberate omission.

In `@packages/appkit/skills/ton-appkit/SKILL.md`:
- Around line 1-4: This SKILL.md file is the intended exception to the
packages/appkit/**/* kebab-case filename rule; verify the build/loader that
enforces kebab-case accepts this exact filename (SKILL.md) for the ton-appkit
entrypoint, and if it does not, either update the loader/config to whitelist
SKILL.md as an exception or rename the file to a kebab-case alternative and
update any imports/references to that symbol; ensure the chosen fix is applied
consistently so the bundler/loader no longer fails on the ton-appkit entrypoint.
🪄 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: ae518727-cd5b-41ba-b1fd-3ccc485b845c

📥 Commits

Reviewing files that changed from the base of the PR and between b6943e0 and 7d38284.

📒 Files selected for processing (11)
  • .claude/skills/add-action-and-hook/SKILL.md
  • .claude/skills/add-ui-component/SKILL.md
  • .claude/skills/kit-dev/SKILL.md
  • .claude/skills/kit-dev/evals.json
  • .claude/skills/kit-dev/skill-reference/recipes.md
  • CLAUDE.md
  • packages/appkit-react/CLAUDE.md
  • packages/appkit/CLAUDE.md
  • packages/appkit/skills/ton-appkit/SKILL.md
  • packages/appkit/skills/ton-appkit/evals.json
  • packages/appkit/skills/ton-appkit/skill-reference/recipes.md
💤 Files with no reviewable changes (2)
  • .claude/skills/add-action-and-hook/SKILL.md
  • .claude/skills/add-ui-component/SKILL.md

Comment thread .claude/skills/kit-dev/skill-reference/recipes.md
Comment thread packages/appkit/skills/ton-appkit/SKILL.md Outdated
@skywardboundd

Copy link
Copy Markdown
Author

waiting for #454

@skywardboundd skywardboundd marked this pull request as draft June 12, 2026 00:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant