{"id":"fa9eee62-5985-4149-8471-cec1af4f1940","shortId":"f55ybH","kind":"skill","title":"sealos-app-builder","tagline":"Build, adapt, and document apps that run inside Sealos Desktop using the Sealos app SDK. Use when creating a new Sealos app, integrating an existing web app into Sealos Desktop, wiring Sealos session data into business features, preparing local iframe-based debugging, or producin","description":"# Sealos App Builder\n\n## Overview\n\nUse this skill to turn a generic web app into a Sealos app that runs inside Sealos Desktop, or to scaffold a new Sealos app from scratch. Focus on the repeatable parts: SDK initialization, session access, language sync, business-data integration, local debugging through a Desktop test app, and publish readiness.\n\nPrefer a simple, teachable implementation that a beginner can understand and extend.\n\n## Core Workflow\n\n### 1. Identify the starting point\n\nClassify the request into one of these paths:\n\n1. Create a new Sealos app from scratch.\n2. Adapt an existing web app to run inside Sealos Desktop.\n3. Add Sealos identity and business-data integration to an app that already renders.\n4. Produce documentation or a tutorial instead of code changes.\n\nIf the repository already contains Sealos-related code, inspect local sources first. In particular:\n\n1. Look for `packages/client-sdk` or equivalent SDK sources.\n2. Look for existing provider apps under `providers/` or similar directories.\n3. Reuse the repository's established framework and routing patterns when they are already in place.\n\nIf the repository does not contain local Sealos sources, use the bundled references in this skill as the baseline.\n\n### 2. Integrate the Sealos app SDK\n\nTreat Sealos Desktop integration as a root-level concern.\n\nBefore using any starter template, install the SDK first:\n\n```bash\npnpm add @labring/sealos-desktop-sdk\n```\n\nUse `npm install @labring/sealos-desktop-sdk` or `yarn add @labring/sealos-desktop-sdk` when the project uses a different package manager.\n\n1. Initialize the SDK once in a client-only root component.\n2. Fetch `getSession()` and `getLanguage()` early.\n3. Store session, language, loading state, and desktop availability in a shared context or store.\n4. Listen for language changes through `EVENT_NAME.CHANGE_I18N` when the app needs runtime language sync.\n5. Add a graceful fallback when the app is opened outside Sealos Desktop.\n\nRead [references/minimal-app-template.md](references/minimal-app-template.md) before implementing the root integration.\nIf the app uses Next.js App Router, also read [references/nextjs-app-router.md](references/nextjs-app-router.md).\n\nUse one of these starter templates:\n\n1. [assets/templates/react/sealos-provider.tsx](assets/templates/react/sealos-provider.tsx) for React.\n2. [assets/templates/vue/use-sealos.ts](assets/templates/vue/use-sealos.ts) for Vue.\n\n### 3. Connect Sealos identity to business data\n\nFor most apps, the key integration is not the iframe itself but the user mapping.\n\n1. Use `session.user.id` as the stable app-level user identifier.\n2. Persist display-friendly fields such as `name`, `avatar`, `k8sUsername`, and `nsid` when useful.\n3. Keep business data in the app's own database and API routes.\n4. Model Sealos user identity as input to your business logic, not as your entire backend.\n\nRead [references/data-integration-patterns.md](references/data-integration-patterns.md) when you need schema or API guidance.\n\n### 4. Prepare local debugging in the real runtime\n\nDo not assume a successful browser render means Sealos integration works.\n\nThe app usually needs to be opened by Sealos Desktop in an iframe for SDK calls like `getSession()` to succeed. When local debugging is part of the task, read [references/local-debug-and-test-app.md](references/local-debug-and-test-app.md).\n\nUse these rules:\n\n1. Explain clearly when a page is outside Sealos Desktop.\n2. Prefer a test app inside Sealos Desktop for end-to-end verification.\n3. Avoid server-side SDK calls.\n\n### 5. Prepare for publishing\n\nWhen the user wants deployment or launch readiness:\n\n1. Verify environment variables.\n2. Verify database connectivity and migrations.\n3. Confirm the app works when launched from Sealos Desktop.\n4. Confirm any cross-app navigation or event usage is valid.\n5. Summarize the remaining manual registration or platform configuration steps.\n\nUse [references/publish-checklist.md](references/publish-checklist.md) as the release checklist.\n\n## Implementation Rules\n\n### Keep the integration simple\n\nDefault to the smallest viable Sealos integration:\n\n1. One root provider or store.\n2. One business identity mapping pattern.\n3. One fallback path for non-Desktop access.\n\nAvoid spreading SDK initialization across multiple pages or components.\n\n### Prefer the repository's real SDK surface\n\nIf the current workspace contains actual Sealos SDK sources or existing Sealos apps:\n\n1. Inspect those sources.\n2. Follow the real exported APIs and types.\n3. Call out repository-specific differences from generic examples.\n\n### Use the official SDK package name\n\nUse `@labring/sealos-desktop-sdk` in generated examples and starter code by default.\n\nOnly deviate from that if the target repository already has an established local workspace alias and the user explicitly wants to preserve it.\n\n## Decision Guide\n\n### If the user asks for \"How do I build a Sealos app?\"\n\nProvide:\n\n1. A short explanation of the runtime model.\n2. A minimal SDK integration example.\n3. A business-data mapping example.\n4. Local debugging guidance through a Sealos Desktop test app.\n\n### If the user asks to modify an existing app\n\nDo this order:\n\n1. Inspect the current app entry point.\n2. Add or refactor a single root Sealos provider.\n3. Wire business APIs to `session.user.id`.\n4. Verify fallback behavior outside Desktop.\n\n### If the user asks for documentation or a tutorial\n\nStructure the output around:\n\n1. What a Sealos app is.\n2. How to initialize the SDK.\n3. How to obtain and use the session.\n4. How to integrate business data.\n5. How to debug through a Desktop test app.\n6. How to publish and verify.\n\n## References\n\nRead only the files needed for the task:\n\n1. [references/sdk-capabilities.md](references/sdk-capabilities.md) for available SDK APIs and runtime behavior.\n2. [references/minimal-app-template.md](references/minimal-app-template.md) for the recommended root integration pattern.\n3. [references/nextjs-app-router.md](references/nextjs-app-router.md) for a concrete Next.js App Router placement example.\n4. [references/data-integration-patterns.md](references/data-integration-patterns.md) for user mapping, database schemas, and API shapes.\n5. [references/local-debug-and-test-app.md](references/local-debug-and-test-app.md) for iframe-based debugging and Desktop test app setup.\n6. [references/publish-checklist.md](references/publish-checklist.md) for launch-readiness steps.","tags":["sealos","app","builder","seakills","labring","agent-skills","ai-agent","claude-code","cloud-native","codex","deployment","docker"],"capabilities":["skill","source-labring","skill-sealos-app-builder","topic-agent-skills","topic-ai-agent","topic-claude-code","topic-cloud-native","topic-codex","topic-deployment","topic-docker","topic-gemini-cli","topic-kubernetes","topic-sealos"],"categories":["seakills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/labring/seakills/sealos-app-builder","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add labring/seakills","source_repo":"https://github.com/labring/seakills","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 17 github stars · SKILL.md body (6,467 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T13:03:12.651Z","embedding":null,"createdAt":"2026-04-19T00:40:54.530Z","updatedAt":"2026-04-22T13:03:12.651Z","lastSeenAt":"2026-04-22T13:03:12.651Z","tsv":"'1':120,133,192,291,377,409,527,570,632,682,758,801,842,892 '2':141,200,246,303,382,420,537,574,638,686,766,808,848,902 '3':152,211,309,387,435,551,580,644,694,772,817,854,911 '4':167,324,448,474,590,779,823,862,922 '5':339,558,602,868,933 '6':877,946 'access':89,652 'across':657 'actual':674 'adapt':6,142 'add':153,273,281,340,809 'alia':734 'alreadi':165,180,224,728 'also':367 'api':446,472,691,820,898,931 'app':3,9,18,26,31,51,62,66,78,102,138,146,163,205,250,334,346,362,365,396,416,441,494,541,583,595,681,756,788,797,805,846,876,918,944 'app-level':415 'around':841 'ask':748,792,832 'assets/templates/react/sealos-provider.tsx':378,379 'assets/templates/vue/use-sealos.ts':383,384 'assum':484 'avail':317,896 'avatar':429 'avoid':552,653 'backend':463 'base':46,939 'baselin':245 'bash':271 'beginn':113 'behavior':826,901 'browser':487 'build':5,753 'builder':4,52 'bundl':238 'busi':40,93,158,392,437,457,640,775,819,866 'business-data':92,157,774 'call':508,557,695 'chang':176,328 'checklist':618 'classifi':125 'clear':529 'client':299 'client-on':298 'code':175,185,717 'compon':302,661 'concern':261 'concret':916 'configur':610 'confirm':581,591 'connect':388,577 'contain':181,232,673 'context':321 'core':118 'creat':22,134 'cross':594 'cross-app':593 'current':671,804 'data':38,94,159,393,438,776,867 'databas':444,576,928 'debug':47,97,477,515,781,871,940 'decis':743 'default':625,719 'deploy':566 'desktop':14,34,71,100,151,254,316,351,502,536,544,589,651,786,828,874,942 'deviat':721 'differ':288,700 'directori':210 'display':423 'display-friend':422 'document':8,169,834 'earli':308 'end':547,549 'end-to-end':546 'entir':462 'entri':806 'environ':572 'equival':197 'establish':216,731 'event':598 'event_name.change':330 'exampl':703,714,771,778,921 'exist':29,144,203,679,796 'explain':528 'explan':761 'explicit':738 'export':690 'extend':117 'fallback':343,646,825 'featur':41 'fetch':304 'field':425 'file':887 'first':189,270 'focus':81 'follow':687 'framework':217 'friend':424 'generat':713 'generic':60,702 'getlanguag':307 'getsess':305,510 'grace':342 'guid':744 'guidanc':473,782 'i18n':331 'ident':155,390,452,641 'identifi':121,419 'ifram':45,403,505,938 'iframe-bas':44,937 'implement':110,356,619 'initi':87,292,656,851 'input':454 'insid':12,69,149,542 'inspect':186,683,802 'instal':267,277 'instead':173 'integr':27,95,160,247,255,359,399,491,623,631,770,865,909 'k8susername':430 'keep':436,621 'key':398 'labring/sealos-desktop-sdk':274,278,282,711 'languag':90,312,327,337 'launch':568,586,951 'launch-readi':950 'level':260,417 'like':509 'listen':325 'load':313 'local':43,96,187,233,476,514,732,780 'logic':458 'look':193,201 'manag':290 'manual':606 'map':408,642,777,927 'mean':489 'migrat':579 'minim':768 'model':449,765 'modifi':794 'multipl':658 'name':428,709 'navig':596 'need':335,469,496,888 'new':24,76,136 'next.js':364,917 'non':650 'non-desktop':649 'npm':276 'nsid':432 'obtain':857 'offici':706 'one':129,372,633,639,645 'open':348,499 'order':800 'output':840 'outsid':349,534,827 'overview':53 'packag':289,708 'packages/client-sdk':195 'page':532,659 'part':85,517 'particular':191 'path':132,647 'pattern':220,643,910 'persist':421 'place':226 'placement':920 'platform':609 'pnpm':272 'point':124,807 'prefer':106,538,662 'prepar':42,475,559 'preserv':741 'produc':168 'producin':49 'project':285 'provid':204,207,635,757,816 'publish':104,561,880 'react':381 'read':352,368,464,521,884 'readi':105,569,952 'real':480,666,689 'recommend':907 'refactor':811 'refer':239,883 'references/data-integration-patterns.md':465,466,923,924 'references/local-debug-and-test-app.md':522,523,934,935 'references/minimal-app-template.md':353,354,903,904 'references/nextjs-app-router.md':369,370,912,913 'references/publish-checklist.md':613,614,947,948 'references/sdk-capabilities.md':893,894 'registr':607 'relat':184 'releas':617 'remain':605 'render':166,488 'repeat':84 'repositori':179,214,229,664,698,727 'repository-specif':697 'request':127 'reus':212 'root':259,301,358,634,814,908 'root-level':258 'rout':219,447 'router':366,919 'rule':526,620 'run':11,68,148 'runtim':336,481,764,900 'scaffold':74 'schema':470,929 'scratch':80,140 'sdk':19,86,198,251,269,294,507,556,655,667,676,707,769,853,897 'sealo':2,13,17,25,33,36,50,65,70,77,137,150,154,183,234,249,253,350,389,450,490,501,535,543,588,630,675,680,755,785,815,845 'sealos-app-build':1 'sealos-rel':182 'server':554 'server-sid':553 'session':37,88,311,861 'session.user.id':411,822 'setup':945 'shape':932 'share':320 'short':760 'side':555 'similar':209 'simpl':108,624 'singl':813 'skill':56,242 'skill-sealos-app-builder' 'smallest':628 'sourc':188,199,235,677,685 'source-labring' 'specif':699 'spread':654 'stabl':414 'start':123 'starter':265,375,716 'state':314 'step':611,953 'store':310,323,637 'structur':838 'succeed':512 'success':486 'summar':603 'surfac':668 'sync':91,338 'target':726 'task':520,891 'teachabl':109 'templat':266,376 'test':101,540,787,875,943 'topic-agent-skills' 'topic-ai-agent' 'topic-claude-code' 'topic-cloud-native' 'topic-codex' 'topic-deployment' 'topic-docker' 'topic-gemini-cli' 'topic-kubernetes' 'topic-sealos' 'treat':252 'turn':58 'tutori':172,837 'type':693 'understand':115 'usag':599 'use':15,20,54,236,263,275,286,363,371,410,434,524,612,704,710,859 'user':407,418,451,564,737,747,791,831,926 'usual':495 'valid':601 'variabl':573 'verif':550 'verifi':571,575,824,882 'viabl':629 'vue':386 'want':565,739 'web':30,61,145 'wire':35,818 'work':492,584 'workflow':119 'workspac':672,733 'yarn':280","prices":[{"id":"10c86206-4207-426a-bbd2-6594304edfa0","listingId":"fa9eee62-5985-4149-8471-cec1af4f1940","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"labring","category":"seakills","install_from":"skills.sh"},"createdAt":"2026-04-19T00:40:54.530Z"}],"sources":[{"listingId":"fa9eee62-5985-4149-8471-cec1af4f1940","source":"github","sourceId":"labring/seakills/sealos-app-builder","sourceUrl":"https://github.com/labring/seakills/tree/main/skills/sealos-app-builder","isPrimary":false,"firstSeenAt":"2026-04-19T00:40:54.530Z","lastSeenAt":"2026-04-22T13:03:12.651Z"}],"details":{"listingId":"fa9eee62-5985-4149-8471-cec1af4f1940","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"labring","slug":"sealos-app-builder","github":{"repo":"labring/seakills","stars":17,"topics":["agent-skills","ai-agent","claude-code","cloud-native","codex","deployment","docker","gemini-cli","kubernetes","sealos"],"license":null,"html_url":"https://github.com/labring/seakills","pushed_at":"2026-04-22T08:50:08Z","description":"AI agent skills for Sealos Cloud — deploy any project, provision databases, object storage & more with one command. Works with Claude Code, Gemini CLI, Codex.","skill_md_sha":"0384c1ef23fd01c8e616971f7eb58c336f379933","skill_md_path":"skills/sealos-app-builder/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/labring/seakills/tree/main/skills/sealos-app-builder"},"layout":"multi","source":"github","category":"seakills","frontmatter":{"name":"sealos-app-builder","description":"Build, adapt, and document apps that run inside Sealos Desktop using the Sealos app SDK. Use when creating a new Sealos app, integrating an existing web app into Sealos Desktop, wiring Sealos session data into business features, preparing local iframe-based debugging, or producing beginner-friendly Sealos app tutorials and starter implementations. Also triggers on \"/sealos-app-builder\"."},"skills_sh_url":"https://skills.sh/labring/seakills/sealos-app-builder"},"updatedAt":"2026-04-22T13:03:12.651Z"}}