START
  │
  ├─ New project? ─────────────────────────────────────────┐
  │     │                                                   │
  │     ├─ Using Anchor? ──► YES ──► Use @solana/web3.js   │
  │     │                                                   │
  │     └─ No Anchor? ──► Use @solana/kit                  │
  │                                                         │
  └─ Existing project? ────────────────────────────────────┤
        │                                                   │
        ├─ Performance issues? ──► Consider migration      │
        │                                                   │
        ├─ Bundle size issues? ──► Consider migration      │
        │                                                   │
        └─ Working fine? ──► Stay with current SDK         │

# Use the analyze-migration.sh script in scripts/
./scripts/analyze-migration.sh /path/to/project

// v1
const connection = new Connection(url, 'confirmed');
const balance = await connection.getBalance(pubkey);

// Kit
const rpc = createSolanaRpc(url);
const { value: balance } = await rpc.getBalance(address).send();

// v1
const keypair = Keypair.fromSecretKey(secretKey);
console.log(keypair.publicKey.toBase58());

// Kit
const signer = await createKeyPairSignerFromBytes(secretKey);
console.log(signer.address);

// v1
const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: sender.publicKey,
    toPubkey: recipient,
    lamports: amount,
  })
);
tx.recentBlockhash = blockhash;
tx.feePayer = sender.publicKey;

// Kit
const tx = pipe(
  createTransactionMessage({ version: 0 }),
  tx => setTransactionMessageFeePayer(sender.address, tx),
  tx => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
  tx => appendTransactionMessageInstruction(
    getTransferSolInstruction({
      source: sender,
      destination: address(recipient),
      amount: lamports(BigInt(amount)),
    }),
    tx
  ),
);

// WRONG - will fail
const amount = 1000000000;

// CORRECT
const amount = 1_000_000_000n;
// or
const amount = BigInt(1000000000);
// or use helper
const amount = lamports(1_000_000_000n);

// If you see: "Encoded binary (base 58) data should be less than 128 bytes"
// Add encoding parameter:
await rpc.getAccountInfo(address, { encoding: 'base64' }).send();

// v1 - synchronous
const keypair = Keypair.generate();

// Kit - MUST await
const keypair = await generateKeyPairSigner();

// v1
const balance = await connection.getBalance(pubkey);

// Kit - don't forget .send()!
const { value: balance } = await rpc.getBalance(address).send();

// Use @solana/compat for conversion
import { fromLegacyPublicKey, toLegacyPublicKey } from '@solana/compat';

const kitAddress = fromLegacyPublicKey(legacyPublicKey);
const legacyPubkey = toLegacyPublicKey(kitAddress);

// v1
transaction.sign(keypair);
// or
const signed = await connection.sendTransaction(tx, [keypair]);

// Kit - use signer pattern
const signedTx = await signTransactionMessageWithSigners(txMessage);
const signature = await sendAndConfirmTransaction(signedTx);

// Keep @solana/web3.js for Anchor interactions
import { Connection, PublicKey } from '@solana/web3.js';
import { Program } from '@coral-xyz/anchor';

// Use Kit for non-Anchor parts if needed
// Bridge with @solana/compat

// v1
const subscriptionId = connection.onAccountChange(pubkey, callback);
connection.removeAccountChangeListener(subscriptionId);

// Kit - use AbortController
const abortController = new AbortController();
const notifications = await rpcSubscriptions
  .accountNotifications(address)
  .subscribe({ abortSignal: abortController.signal });

for await (const notification of notifications) {
  // handle notification
}
// To unsubscribe:
abortController.abort();

// v1
const versionedTx = new VersionedTransaction(messageV0);

// Kit - transactions are versioned by default
const tx = createTransactionMessage({ version: 0 });

// v1
const lookupTable = await connection.getAddressLookupTable(tableAddress);
const messageV0 = new TransactionMessage({...}).compileToV0Message([lookupTable.value]);

// Kit
// Lookup tables are handled in transaction compilation
// See resources/lookup-tables-example.md

import { createSolanaClient, sendSol } from 'gill';

const client = createSolanaClient({ rpcUrl });
await sendSol(client, { from: signer, to: recipient, amount: lamports(1n) });

solana-kit-migration/
├── SKILL.md                          # This file
├── scripts/
│   ├── analyze-migration.sh          # Codebase analysis script
│   └── detect-patterns.js            # Pattern detection utility
├── resources/
│   ├── api-mappings.md               # Complete API reference
│   ├── compatibility-matrix.md       # SDK compatibility info
│   └── package-comparison.md         # Feature comparison
├── examples/
│   ├── v1-to-kit/                    # Migration examples
│   │   ├── basic-transfer.md
│   │   ├── token-operations.md
│   │   └── subscription-handling.md
│   └── mixed-codebase/               # Hybrid approach examples
│       └── anchor-with-kit.md
└── docs/
    └── edge-cases.md                 # Detailed edge cases