@laitszkin/apollo-toolkit 2.5.0 → 2.7.0

package/AGENTS.md

@@ -32,17 +32,21 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
 - Users can summarize mistakes into a learning error book and render it to PDF.
+- Users can build or review marginfi protocol integrations using official SDK, CLI, protocol, and The Arena documentation.
 - Users can create or maintain `AGENTS.md` so project constraints stay aligned with the repository.
 - Users can turn novel content into a loopable short-form video with generated assets.
 - Users can publish structured GitHub issues or feature proposals with auth fallbacks.
 - Users can prepare and open open-source pull requests from existing changes.
 - Users can generate storyboard image sets from chapters, novels, articles, or scripts.
+- Users can configure OpenClaw from official documentation, including `~/.openclaw/openclaw.json`, skills loading, SecretRefs, CLI edits, and validation or repair workflows.
 - Users can record multi-account spending and balance changes in monthly Excel ledgers with summary analytics and charts.
 - Users can review the current git change set from an unbiased reviewer perspective to find abstraction opportunities and simplification candidates.
 - Users can process GitHub pull request review comments and resolve addressed threads.
 - Users can perform repository-wide code reviews and publish confirmed findings as GitHub issues.
 - Users can schedule a bounded project runtime window, stop it automatically, and analyze module health from captured logs.
+- Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
+- Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
 - Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.
 - Users can generate 30-60 second short videos directly from text prompts.
 - Users can prepare and publish versioned releases with changelog and tag workflows.

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.7.0] - 2026-03-20
+
+### Added
+- Add `openclaw-configuration` for explaining, editing, validating, and troubleshooting OpenClaw configuration from the current official docs, including `~/.openclaw/openclaw.json`, skills config, secrets, and CLI workflows.
+- Add bundled OpenClaw configuration references covering the official doc map, config option guide, and operational best practices.
+
+### Changed
+- Update `fix-github-issues` to require temporary worktree and local branch cleanup as part of direct-push or PR completion, with explicit cleanup verification before finishing.
+- Update `learn-skill-from-conversations` to treat post-completion cleanup or finalization follow-ups as evidence that the owning workflow's done criteria need tightening.
+- Update the repository skill inventory and project capability docs to include OpenClaw configuration support.
+
+## [v2.6.0] - 2026-03-20
+
+### Added
+- Add `jupiter-development` for building Jupiter-based Solana integrations from current official docs, including swap, token, price, lend, trigger, recurring, and portfolio surfaces.
+- Add `marginfi-development` for building or reviewing marginfi integrations with official SDK, CLI, protocol, and The Arena references.
+- Add `solana-development` for native Solana Rust programs and Rust client workflows grounded in official Solana documentation.
+
+### Changed
+- Update `learn-skill-from-conversations` to prefer inventorying the current skill catalog, weighting user corrections and error-driven lessons more heavily, and tightening when to update an existing skill versus creating a new one.
+- Update `codex-memory-manager` so memory reports include already-stored relevant preferences when users ask what memory exists or why a known preference was omitted.
+- Refresh new protocol reference snapshots against current official Jupiter, marginfi, and Solana docs before release.
+
 ## [v2.5.0] - 2026-03-19
 
 ### Changed

package/README.md

@@ -21,19 +21,23 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - generate-spec
 - harden-app-security
 - improve-observability
+- jupiter-development
 - learn-skill-from-conversations
 - learning-error-book
+- marginfi-development
 - maintain-project-constraints
 - maintain-skill-catalog
 - novel-to-short-video
 - open-github-issue
 - open-source-pr-workflow
 - openai-text-to-image-storyboard
+- openclaw-configuration
 - record-spending
 - resolve-review-comments
 - review-change-set
 - review-codebases
 - scheduled-runtime-health-check
+- solana-development
 - systematic-debug
 - text-to-short-video
 - version-release

package/codex-memory-manager/SKILL.md

@@ -114,6 +114,8 @@ python3 ~/.codex/skills/codex-memory-manager/scripts/sync_memory_index.py \
   - which categories were created or updated
   - whether a new category was introduced
   - whether the AGENTS memory index changed
+- When the user asks what memory exists or asks why a known preference was not mentioned, include the already-stored preferences that are directly relevant to the question instead of summarizing only newly added entries.
+- When a stable preference already existed and was still reinforced by recent chats, say that it remains stored and point to the category where it lives.
 - If no durable preferences were found, say so explicitly and avoid creating placeholder memory files.
 
 ## Guardrails

package/fix-github-issues/SKILL.md

@@ -16,8 +16,8 @@ description: Resolve issues from remote GitHub repositories via GitHub CLI (`gh`
 
 - Evidence: Verify repository context, fetch remote issue details, and derive expected behavior from issue text before coding.
 - Execution: Select the issue, open an isolated worktree by default, fix it through `systematic-debug`, validate locally, then hand off to the delivery workflow that matches the user's request.
-- Quality: Keep scope limited to the selected issue, capture exact validation commands, and preserve issue linkage in the final PR or commit message.
-- Output: Finish with either a linked PR or a direct pushed commit, then clean up the temporary worktree when the work is complete.
+- Quality: Keep scope limited to the selected issue, capture exact validation commands, preserve issue linkage in the final PR or commit message, and treat temporary worktree cleanup as part of completion rather than an optional follow-up.
+- Output: Finish with either a linked PR or a direct pushed commit, then clean up the temporary worktree plus any matching local branch before reporting completion.
 
 ## Overview
 
@@ -89,10 +89,12 @@ python3 scripts/list_issues.py --limit 50 --state open
   - executed test commands and results
 - Include issue-closing reference (for example, `Closes #<issue-number>`) whenever a PR is opened.
 
-### 8) Clean up the temporary worktree after PR creation
+### 8) Clean up the temporary worktree after PR creation or direct push
 
 - Once the PR is opened or the direct push is complete and no more work is needed in that isolated tree, remove the worktree you created for the fix.
 - Also clean up the matching local branch reference if it is no longer needed locally.
+- Verify the cleanup with `git worktree list` and confirm the temporary path no longer appears before finishing.
+- If the worktree cannot be removed because of uncommitted changes or a still-checked-out branch, resolve that state immediately instead of leaving cleanup for a later user request.
 
 ## Included Script
 

package/jupiter-development/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: jupiter-development
+description: Build integrations against Jupiter's official Solana APIs and SDKs, including Ultra Swap, Metis Swap, Tokens API V2, Price API V3, Lend, Trigger, Recurring, and Portfolio. Use when implementing Jupiter-based swaps, token search, pricing, lending, DCA, limit-order, or portfolio features, or when updating code that depends on Jupiter official developer docs.
+---
+
+# Jupiter Development
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: If official Jupiter docs are unavailable, stop and report the missing source instead of guessing endpoint behavior.
+
+## Standards
+
+- Evidence: Treat `https://dev.jup.ag/llms.txt` and linked official pages as the source of truth; re-check them when the task depends on current API behavior.
+- Execution: Identify the exact Jupiter product first, then implement against the narrowest official API or SDK that fits the job.
+- Quality: Prefer the default happy-path integrations before custom transaction assembly, and call out routing, auth, fee, and rate-limit tradeoffs explicitly.
+- Output: Leave the user with working integration changes plus a short note covering which Jupiter surface was used and which official docs were followed.
+
+## Goal
+
+Implement Jupiter-backed Solana features safely by following the current official developer documentation instead of relying on stale examples or assumptions.
+
+## Required Workflow
+
+### 1) Reconfirm the official surface before coding
+
+- Start from `https://dev.jup.ag/llms.txt` to discover the current product map and page URLs.
+- Read only the product pages needed for the task.
+- If the task depends on exact request or response fields, follow through to the linked API reference or OpenAPI page before editing code.
+
+### 2) Choose the right Jupiter integration path
+
+- For token swaps, default to Ultra Swap.
+  - Use `GET /ultra/v1/order` plus `POST /ultra/v1/execute` for the standard path with the least integration work.
+  - Use Metis Swap only when the app must own quote-to-transaction construction, compose instructions, or integrate through CPI/Flash Fill style flows.
+- For token discovery and token metadata, use Tokens API V2.
+  - Use search for symbol, name, or mint lookup.
+  - Use tag/category/recent endpoints for discovery experiences such as verified lists, trending tokens, or newly tradable assets.
+- For USD token pricing, use Price API V3.
+  - Expect `null` or missing prices for assets that Jupiter considers unreliable.
+  - Do not invent fallback prices without telling the user.
+- For lending, use Jupiter Lend.
+  - Use the REST API for Earn when HTTP access is enough.
+  - Use `@jup-ag/lend` and `@jup-ag/lend-read` when the task needs instruction building, on-chain composition, flashloans, Borrow flows, or read-side analytics.
+- For advanced trading automations, use the product-specific APIs instead of overloading Swap.
+  - Trigger for limit-order and stop-style flows.
+  - Recurring for DCA.
+  - Portfolio for wallet position aggregation.
+
+### 3) Apply Jupiter-specific guardrails while implementing
+
+- Treat Jupiter hostnames and auth rules as time-sensitive.
+  - Current official docs still show some `lite-api.jup.ag` quick-start examples.
+  - Current migration and Portal docs recommend `api.jup.ag` with `x-api-key`.
+  - Reconfirm the exact hostname and auth rule for the chosen product before coding.
+- Respect Jupiter Portal rate limits and keep API keys in configuration rather than source control.
+- Do not add optional swap parameters blindly.
+  - Payer, referral, fee, and router-selection fields can change routing, fee behavior, or gasless support.
+  - Re-read the exact product page before shipping these options.
+- Match the fee model to the integration path.
+  - Ultra handles the quote and execution flow end to end.
+  - Metis gives more transaction control but also pushes more assembly responsibility onto the integrator.
+- Treat Jupiter token and price data as curated but evolving.
+  - Tokens V2 responses can change as Jupiter improves the schema.
+  - Price V3 intentionally withholds unreliable prices.
+- For Jupiter Lend advanced recipes, expect versioned transactions, address lookup tables, and sometimes extra compute budget.
+- Never commit private keys. Use environment variables, wallet adapters, secure signers, or managed key systems.
+
+### 4) Verify the integration path end to end
+
+- Confirm the base URL, auth header, and required parameters match the official docs you used.
+- Verify that any routing, payer, referral, or fee assumptions still hold after optional parameters are added.
+- When building transactions manually, verify quote endpoint compatibility, instruction order, compute budget, address lookup tables, and signing flow.
+- When the task involves on-chain actions, report any remaining environment needs clearly, such as API keys, RPC endpoints, or wallet secrets that were intentionally not embedded.
+
+## Reference Files
+
+- Read `references/official-docs.md` for the condensed official guidance and page map before diving into deeper Jupiter pages.
+
+## Output Expectations
+
+When finishing a Jupiter task:
+
+- state which Jupiter product surface was used
+- mention the main official pages consulted
+- call out any known tradeoffs such as rate limits, routing restrictions, null prices, or SDK versus REST constraints

package/jupiter-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Jupiter Development"
+  short_description: "Build against Jupiter's official Solana APIs and SDKs."
+  default_prompt: "Use $jupiter-development to build or update this Jupiter integration by confirming the current official docs first, choosing the correct Jupiter API or SDK surface, and implementing with the right routing, auth, rate-limit, and transaction-construction guardrails."

package/jupiter-development/references/official-docs.md

@@ -0,0 +1,157 @@
+# Jupiter Official Docs Reference
+
+Snapshot source: official Jupiter developer docs reviewed on 2026-03-20 from `https://dev.jup.ag/llms.txt` and linked first-party pages.
+
+## 1. Always refresh from these official entry points
+
+- Docs index: `https://dev.jup.ag/llms.txt`
+- Get started: `https://dev.jup.ag/get-started`
+- Developer portal and API keys: `https://dev.jup.ag/portal/setup.md`
+- Rate limits: `https://dev.jup.ag/portal/rate-limit.md`
+- Ultra docs root: `https://dev.jup.ag/docs/ultra-api`
+- Swap docs root: `https://dev.jup.ag/docs/swap/index.md`
+- Tokens docs root: `https://dev.jup.ag/docs/tokens/v2/token-information.md`
+- Price docs root: `https://dev.jup.ag/docs/price/index.md`
+- Lend docs root: `https://dev.jup.ag/docs/lend/index.md`
+
+If a task depends on exact schemas, jump from those pages into the matching OpenAPI reference before coding.
+
+## 2. Product selection cheatsheet
+
+| Need | Official Jupiter surface | Notes |
+| --- | --- | --- |
+| Best default swap flow | Ultra API `/ultra/v1/order` + `/ultra/v1/execute` | Current get-started docs point new integrators here first. |
+| Custom swap transaction or CPI composition | Metis Swap API | Use the lower-level swap docs only when the app must own quote/build behavior or compose instructions manually. |
+| Token search, metadata, verification, discovery | Tokens API V2 | Search by symbol, name, mint, tag, category, or recency. |
+| USD token prices | Price API V3 | Heuristic price engine; unreliable tokens may return `null`. |
+| Deposit-and-earn yield | Jupiter Lend Earn API or SDK | REST is enough for simple Earn flows; SDK gives instruction-level control. |
+| Borrow, repay, flashloan, or CPI lending | `@jup-ag/lend` plus `@jup-ag/lend-read` | Use SDK and product docs for instruction building and analytics. |
+| Limit orders / TP-SL style automation | Trigger API | Trigger V2 uses JWT auth; Trigger V1 remains documented for legacy flows. |
+| DCA | Recurring API | Time-based recurring orders. |
+| Wallet position aggregation | Portfolio API | Beta status. |
+
+## 3. Auth and operational rules
+
+- Current official docs say `api.jup.ag` requires `x-api-key`.
+- Current get-started examples still show public `lite-api.jup.ag` usage for some flows, while Jupiter's update/migration docs say deprecation was postponed and migration toward `api.jup.ag` is in progress.
+- Treat hostname choice as a time-sensitive implementation detail and refresh the exact product page before coding.
+- Generate keys at `https://portal.jup.ag`.
+- Rate limits are per account, not per key.
+- Free tier: 60 requests per 60 seconds.
+- Pro tiers: 10-second sliding windows; the Price API gets its own bucket on Pro.
+- Do not assume that creating more API keys increases throughput.
+
+## 4. Ultra and Metis swap essentials
+
+Primary docs:
+
+- `https://dev.jup.ag/get-started`
+- `https://dev.jup.ag/docs/ultra-api`
+- `https://dev.jup.ag/docs/swap/index.md`
+- `https://dev.jup.ag/docs/swap/get-quote`
+- `https://dev.jup.ag/docs/swap/build-swap-transaction`
+- `https://dev.jup.ag/docs/swap/build-swap-transaction#build-your-own-transaction-with-flash-fill-or-cpi`
+
+### Default path: Ultra API
+
+- Current get-started guidance points integrators to `GET /ultra/v1/order` and `POST /ultra/v1/execute`.
+- Use this path for the least integration work and the official default trade flow.
+
+### Advanced path: Metis Swap API
+
+- Use the lower-level swap docs when the integrator must own quote handling, transaction assembly, CPI composition, or Flash Fill style flows.
+- Reconfirm the current endpoint family on the exact swap page you use because Jupiter has been migrating between public and Portal-backed hosts.
+
+### Routing and option guardrails
+
+- Optional payer, referral, fee, or router-selection parameters are not neutral.
+- Re-read the exact product page before enabling them because they can affect routing, fees, or gasless support.
+- Do not assume all examples on older swap pages still describe the default production path.
+
+## 5. Tokens API V2 essentials
+
+Base URL: `https://api.jup.ag/tokens/v2`
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/tokens/v2/token-information.md`
+- `https://dev.jup.ag/docs/tokens/organic-score.md`
+
+Important behaviors:
+
+- Search supports symbol, name, and mint-address lookup.
+- Tag queries support curated groups such as `verified` and `lst`.
+- Category queries support discovery sets such as `toporganicscore`, `toptraded`, and `toptrending`.
+- Recent tokens are keyed off first pool creation time, not token mint time.
+- Responses include metadata and market-quality signals such as organic score, holder count, market cap, liquidity, and trading stats.
+- The docs explicitly warn that the response schema may change as the API evolves.
+
+Organic score is meant to represent genuine token activity and health using wallet, liquidity, and trading signals while filtering out bot-like or wash-trade patterns.
+
+## 6. Price API V3 essentials
+
+Base URL: `https://api.jup.ag/price/v3`
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/price/index.md`
+- `https://dev.jup.ag/docs/price/v3.md`
+- `https://dev.jup.ag/guides/how-to-get-token-price.md`
+
+Important behaviors:
+
+- Price V3 derives prices from the last swapped price and validates them with liquidity and market-health heuristics.
+- Up to 50 mint addresses can be queried per request according to the official guide.
+- Missing or `null` prices are expected for tokens that fail Jupiter's reliability checks.
+- Do not treat missing prices as transient transport errors by default.
+
+## 7. Jupiter Lend essentials
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/lend/index.md`
+- `https://dev.jup.ag/docs/lend/api-vs-sdk.md`
+- `https://dev.jup.ag/docs/lend/program-addresses.md`
+- `https://dev.jup.ag/docs/lend/advanced/index.md`
+
+Packages mentioned by the official docs:
+
+- `@jup-ag/lend`
+- `@jup-ag/lend-read`
+- `@solana/web3.js`
+
+Practical split:
+
+- Use the REST API for straightforward Earn deposit and withdrawal flows.
+- Use the SDK when you need Borrow flows, CPI, flashloans, batched operations, address lookup tables, or read-side analytics.
+- For advanced recipes such as multiply, unwind, vault swap, and flashloans, expect large multi-instruction transactions and add compute budget when needed.
+- Public RPC endpoints are not recommended for production; the docs suggest dedicated providers.
+
+## 8. Other important Jupiter APIs
+
+### Trigger
+
+- Docs root: `https://dev.jup.ag/docs/trigger/index.md`
+- Trigger V2 uses a challenge-response auth flow and returns a JWT for subsequent requests.
+- Use it for single price orders, OCO, and OTOCO flows.
+
+### Recurring
+
+- Docs root: `https://dev.jup.ag/docs/recurring/index.md`
+- Use it for time-based DCA orders.
+- Jupiter keeper bots handle recurring execution after setup.
+
+### Portfolio
+
+- Docs root: `https://dev.jup.ag/docs/portfolio/index.md`
+- Beta API for wallet positions across Solana protocols, including Jupiter-specific positions.
+
+## 9. Implementation checklist
+
+- Confirm the exact Jupiter product surface first.
+- Confirm the latest official page and API version before editing code.
+- Confirm whether the chosen host requires `x-api-key`, and keep any key out of source control.
+- Preserve the default routing path unless the product requirement truly needs advanced payer, fee, or router controls.
+- Treat `null` token prices as a valid product outcome.
+- Use SDK flows for Jupiter Lend borrow, CPI, flashloan, and analytics work.
+- Report any remaining API-key, RPC, or wallet requirements explicitly.

package/learn-skill-from-conversations/SKILL.md

@@ -15,7 +15,7 @@ description: Learn and evolve the local skill library from recent Codex conversa
 ## Standards
 
 - Evidence: Extract recent Codex session history first and derive reusable lessons only from actual conversation patterns.
-- Execution: Prefer creating a new skill unless the overlap with an existing skill is clearly strong, then apply the change through `skill-creator`.
+- Execution: Inventory the current skill catalog before editing, prioritize repeated requests, user corrections, reported errors, and post-completion follow-up asks that reveal missing closure, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
 - Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, and validate every changed skill.
 - Output: Report the analyzed sessions, extracted lessons, created or updated skills, and the reasoning behind each decision.
 
@@ -46,16 +46,27 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 ### 2) Derive reusable lessons
 
 - Identify repeated user needs, recurring friction, and repeated manual workflows.
+- Give extra weight to moments where the user corrected the agent, rejected an earlier interpretation, or pointed out a missing preference or requirement.
+- Give extra weight to user-reported errors, regressions, or avoidable mistakes, then ask how a skill can prevent repeating that failure mode.
+- Treat a user follow-up that asks for cleanup or an omitted finalization step immediately after the assistant reported completion as evidence that the workflow's done criteria were incomplete.
+- When that kind of follow-up recurs, tighten the owning skill's completion checklist before considering any new-skill extraction.
 - Ignore one-off issues that do not provide reusable value.
+- Distinguish between:
+  - repeated trigger intent that deserves a new skill
+  - repeated workflow fragments across multiple skills that should be extracted into a shared skill
+  - skill gaps that are better handled by tightening an existing skill's guardrails
 
 ### 3) Decide new skill vs existing skill (default: new skill)
 
+- First read the relevant skills already present in the working repository so you do not create a duplicate under a different name.
 - Prefer creating a new skill.
 - Edit an existing skill only when the lesson is strongly related.
 - Treat relation as strong only when all three conditions hold:
   - Same primary trigger intent.
   - At least 70% workflow overlap.
   - The update does not dilute the existing skill's scope.
+- When the recurring lesson is mainly about preventing a known mistake, prefer updating the existing skill that should have prevented it instead of creating a parallel skill.
+- When several skills repeat the same narrow workflow fragment, prefer extracting that fragment into a dedicated shared skill instead of copying the same guidance again.
 - If uncertain, create a new skill instead of expanding an old one.
 
 ### 4) Apply changes through skill-creator
@@ -76,7 +87,7 @@ python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-p
 
 ### 6) Report result
 
-- Summarize analyzed sessions, extracted lessons, created/updated skills, and why each decision was made.
+- Summarize analyzed sessions, repeated needs, user corrections, error-driven lessons, created/updated skills, and why each decision was made.
 
 ## Guardrails
 

package/marginfi-development/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/marginfi-development/README.md

@@ -0,0 +1,31 @@
+# Marginfi Development
+
+`marginfi-development` is a reusable skill for building or reviewing integrations on the marginfi protocol with official documentation as the source of truth.
+
+It helps an agent:
+
+1. Choose the correct marginfi development surface.
+2. Reconfirm official addresses, groups, and environment details.
+3. Implement or explain deposits, borrows, repayments, withdrawals, flash loans, liquidations, or permissionless banks.
+4. Map raw `mfi-v2` instructions and errors when SDK helpers are not enough.
+
+## Repository layout
+
+- `SKILL.md`: trigger rules, workflow, and guardrails
+- `agents/openai.yaml`: agent-facing metadata
+- `references/official-development-notes.md`: condensed official development guidance
+- `references/source-index.md`: quick source routing for official docs
+
+## Main use cases
+
+Use this skill for:
+
+- marginfi SDK integration work
+- Solana bots or backends that interact with marginfi
+- bank configuration and The Arena permissionless-bank flows
+- flash-loan or liquidation implementation reviews
+- raw instruction or error mapping against `mfi-v2`
+
+## License
+
+MIT. See `LICENSE`.

package/marginfi-development/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: marginfi-development
+description: Build or analyze integrations on the Solana-based marginfi protocol using the official TypeScript SDK, Rust CLI, and protocol docs. Use when implementing or reviewing marginfi deposits, withdrawals, borrows, repayments, flash loans, liquidations, permissionless banks, bank configuration, account-health logic, or raw instruction mapping, and ground the work in official marginfi documentation before coding.
+---
+
+# Marginfi Development
+
+## Dependencies
+
+- Required: none.
+- Conditional: `answering-questions-with-research` when the user needs marginfi guidance combined with fresh external verification or local repository discovery.
+- Optional: none.
+- Fallback: If official docs do not confirm a requested parameter, address, or workflow, say so explicitly instead of guessing.
+
+## Standards
+
+- Evidence: Start from official marginfi docs and official source links, and re-check time-sensitive values before hardcoding them.
+- Execution: Pick the correct integration surface first (TypeScript SDK, Rust CLI, or raw program instructions), then scope the exact bank, group, account, and environment involved.
+- Quality: Preserve Solana and Anchor conventions, validate margin account health assumptions, and never invent bank config or oracle defaults.
+- Output: Provide copy-pastable implementation steps, the exact official source pages consulted, and concrete caveats for unresolved risks.
+
+## Goal
+
+Build or review marginfi integrations with the smallest correct implementation that still respects the protocol's account model, bank risk parameters, oracle rules, and operational constraints.
+
+## Workflow
+
+### 1) Classify the task before coding
+
+Map the request to one of these paths:
+
+- application integration with the TypeScript SDK
+- operational/admin work with the Rust CLI
+- raw on-chain instruction work against `mfi-v2`
+- permissionless bank creation in The Arena
+- liquidations, health, or risk-model analysis
+- flash loan composition
+
+Then load only the matching reference sections from `references/official-development-notes.md`.
+
+### 2) Reconfirm official docs when values can drift
+
+Re-check live official docs when the task depends on:
+
+- current program or group addresses
+- package names or environment configs
+- current bank parameters or listing rules
+- The Arena flows or permissionless-bank requirements
+
+Use `references/source-index.md` to jump to the right official page quickly.
+
+### 3) Choose the correct development surface
+
+#### TypeScript SDK
+
+Use for frontends, bots, services, scripts, or integration tests.
+
+- Start with `MarginfiClient.fetch(getConfig(...), wallet, connection)`.
+- Fetch or create the authority's marginfi account before user actions.
+- Resolve banks by token symbol, mint, or public key before depositing, borrowing, repaying, or withdrawing.
+- Prefer SDK helpers for instruction construction, transaction processing, flash loans, and account reloads.
+
+#### Rust CLI
+
+Use for operator workflows, group or bank administration, and quick protocol interaction from the terminal.
+
+- Configure the correct profile and environment first.
+- Use the CLI for account creation, deposits, borrows, repayments, withdrawals, transfers, emissions setup, and bank-management flows.
+- When creating or updating banks, provide explicit config values; do not infer hidden defaults.
+
+#### Raw program work
+
+Use when you need exact instruction names, account constraints, or error mapping.
+
+- Read the `mfi-v2` instruction and error sections first.
+- Keep flash-loan state transitions and end-instruction indexing exact.
+- Map protocol errors back to the user-visible cause instead of returning opaque Solana failures.
+
+### 4) Apply the task-specific playbook
+
+#### Deposits / borrows / withdrawals / repayments
+
+- Confirm the target group and bank.
+- Load or create the user's marginfi account.
+- Fetch fresh bank data and oracle-backed pricing before reasoning about health.
+- Use SDK or CLI helpers instead of hand-writing instructions unless the task explicitly needs raw instruction control.
+
+#### Flash loans
+
+- Treat flash loans as a begin/end instruction pair or use the SDK helper that builds the full transaction.
+- Ensure the end instruction index is correct and that every temporary borrow is repaid within the same transaction.
+- Watch for flash-loan-specific errors such as illegal nesting or missing end instructions.
+
+#### Permissionless banks / The Arena
+
+- Collect the mint, oracle setup, risk tier, asset/liability weights, deposit and borrow limits, operational state, and rate configuration before coding.
+- Use the official The Arena guidance and listing criteria as the source of truth.
+- Surface any missing config explicitly; never invent safe-looking defaults.
+
+#### Liquidations and health analysis
+
+- Distinguish collateral, borrow-only, and isolated assets.
+- Explain how asset weights, liability weights, utilization-based rates, and oracle staleness checks affect account health.
+- Use official terminology when describing liquidatable states and liquidation flows.
+
+### 5) Respect protocol guardrails
+
+- marginfi relies on Pyth and Switchboard oracle feeds with confidence and staleness checks; do not assume any quoted price is always usable.
+- Interest rates are utilization-based and piecewise; account economics depend on bank config, not just spot balances.
+- Current docs describe verified builds, audits, fuzz testing, and bug-bounty coverage; do not bypass those assumptions when proposing deployment or upgrade steps.
+
+### 6) Output expectations
+
+When finishing marginfi work:
+
+- name the exact official pages consulted
+- state the chosen integration surface
+- list the concrete accounts, banks, and env values the implementation needs
+- call out any unverified addresses, parameters, or bank settings
+- keep examples minimal and directly runnable when possible
+
+## References
+
+- `references/official-development-notes.md`: condensed marginfi development guidance from official docs.
+- `references/source-index.md`: official page index and when to consult each source.

package/marginfi-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Marginfi Development"
+  short_description: "Build or review integrations on the marginfi protocol"
+  default_prompt: "Use $marginfi-development to ground the task in official marginfi docs, choose the correct development surface (TypeScript SDK, Rust CLI, or raw program instructions), load the relevant reference sections, and then implement or explain the smallest correct marginfi integration without guessing bank config, oracle setup, or protocol addresses."