SEMOSS

Use when adding a logged-in user menu, profile dropdown, logout button, or a top navigation bar to a SEMOSS app. Covers installing the shadcn/ui dropdown-menu primitive (@radix-ui/react-dropdown-menu), building a UserProfileMenu (shows the user name + logout), a MainNavigation bar, and rendering the nav inside InitializedLayout. Assumes auth is already wired (AuthProvider/useAuth, LoginPage, AuthorizedLayout — shipped in the template). Do not use for the login flow itself (already in the base) or for shadcn setup in general.

Use when publishing, uploading, or updating a SEMOSS app — choosing among the three deploy tiers (manual UI zip, the semoss_asset_sync.py iterate flow, or the ai-repo submit pipeline), switching between named environments (local/preprod/prod), writing client/.env.local before a build, or handling SSL/proxy errors during upload. Do not use for the ai-repo CLI command reference specifically (see semoss-ai-repo) or for editing tool manifests (see semoss-mcp-manifest).

Use when adding, editing, or wiring up a SEMOSS MCP tool manifest — mcp/py_mcp.json (Python tools) or mcp/pixel_mcp.json (Java reactors). Covers the manifest schema, the _meta fields (resourceURI, SMSS_MCP_EXECUTION, displayLocation, loadingMessage), mapping a tool's resourceURI to a hash route in Router.tsx, default vs custom UI, and when to fall back to the MakePythonMCP/MakePixelMCP regenerator reactors. Do not use for the deploy/upload flow (see semoss-deploy) or writing the tool logic itself (Java reactor / Python tool rules live in CLAUDE.md).

Use when working with the SEMOSS platform control plane via the connected MCP servers — creating/publishing/tagging projects (Semoss_project_manager), creating/querying databases and fetching schema (Semoss_database_helper), or pulling platform guidance (Semoss_Platform_Instructions). Covers the project lifecycle, the MCP project tag that gates Playground-chat visibility, standalone-vs-MCP app modes, and which of the platform MCP's frontend claims to ignore. Do not use for in-app SDK calls from React (see CLAUDE.md + the engine skills) or for the deploy mechanics (see semoss-deploy).

Use when submitting a SEMOSS app into the review/repository pipeline with the ai-repo CLI — logging in, registering an app (create-app), publishing a zipped version (publish), and checking workflow status (status, versions). Covers the command set, publish gotchas (build first, what gets zipped, what's excluded), and where credentials are stored. Assumes the ai-repo binary is already installed. Do not use for iterating against a live instance (that's scripts/claude/semoss_asset_sync.py — see semoss-deploy) or for manual UI zip uploads.

Use when writing code in an app that queries a relational or graph database on the platform, running SELECTs, inserts, updates, deletes, or fetching schema/table structure. Covers the SqlQuery(), SqlQueryBase64(), and GetDatabaseTableStructure() pixel commands via the Semoss SDK, plus listing databases with MyEngines(engineTypes=["DATABASE"]). Do not use for LLM calls (see semoss-model) or vector database queries (see semoss-vector).

Use when writing code in an app that calls an LLM, embedding model, or other model engine, OR when listing/selecting models the user has access to. Covers the LLM() and MyEngines() pixel commands via the Semoss SDK, including prompt/completion calls, conversational history, image inputs, and parsing model responses. Do not use for vector database queries (see semoss-vector) or raw SQL/graph queries (see semoss-database).

Use when the user wants to add JUnit/Mockito tests for Java reactors, set up pre-commit hooks (husky + the pre-commit framework), or wire GitHub Actions CI (lint + unit-test workflows) to a SEMOSS app. The base template ships none of this to stay lean — this skill carries the full, working setup as reference files under reference/ that you copy back in and adapt. Do not use for the deploy flow (see semoss-deploy) or routine linting, which is just `pnpm fix` (Biome) at the repo root.

Use BEFORE starting a non-trivial task to recall prior lessons, and IMMEDIATELY when the user corrects you, accepts a non-obvious approach, or you hit a subtle gotcha — to persist the lesson for future sessions. Covers SearchMemories, GetMemory, SaveMemoryCandidate, and MarkVerified from the Agent_Memory MCP. Skip entirely if no Agent_Memory MCP is attached to the current app.

Use when compiling, building, or publishing the React app after making changes to source files — at the end of any turn that edited client code, or when the user asks to build, rebuild, or deploy. Invoke the BuildAndPublishApp tool with the project id. Do not attempt to run node, npm, pnpm, or any JavaScript build command via Bash — the sandbox blocks node execution, and BuildAndPublishApp is the only supported build path.

Use when writing code in an app that queries a relational or graph database on the platform, running SELECTs, inserts, updates, deletes, or fetching schema/table structure. Covers the SqlQuery(), SqlQueryBase64(), and GetDatabaseTableStructure() pixel commands via @semoss/sdk's runPixel, plus listing databases with MyEngines(engineTypes=["DATABASE"]). Do not use for LLM calls (see model-engine) or vector database queries.

Implementing two-step image upload + LLM pixel call (SEMOSS pattern)

Use when writing code in an app that calls an LLM, embedding model, or other model engine, OR when listing/selecting models the user has access to. Covers the LLM() and MyEngines() pixel commands via @semoss/sdk's runPixel, including prompt/completion calls, conversational history, image inputs, and parsing model responses. Do not use for vector database queries (see semoss-vector) or guardrail engines (see semoss-guardrail).

Use when writing Python in a SEMOSS app — `py/mcp_driver.py`, helper modules, or any code that runs inside the SEMOSS Python runtime. Covers what SEMOSS injects (`ROOT`, active insight context), what to import from `ai_server` / `semoss` / `smssutil`, the `@mcp_metadata` decorator for exposing MCP tools, and how Python reaches Pixel via `Insight().run_pixel(...)`. For what Pixel commands to actually run, see the `database`, `model`, and `vector` skills. Do not use for Java reactor authoring or frontend `@semoss/sdk` calls.

Use when writing code in an app that creates, lists, renames, pins, or deletes playground rooms, reads/updates room options (model, system prompt, MCPs, temperature), or reads chat history from a room. Covers CreatePlaygroundRoom, GetPlaygroundRooms, GetWorkspaceRooms, RenameRoom, PinRoom, RemoveUserRoom, SetRoomForInsight, GetRoomOptions, UpdateRoomOptions, GetPlaygroundMessages, and AskCOTRoom / COTRoomResult via @semoss/sdk's runPixel. Do not use for LLM completions (see model) or document/vector ingestion (see vector).

Use when writing code in an app that does semantic search, RAG, or ingests documents into a vector database on the platform — running nearest-neighbor queries, listing/adding/removing documents, or feeding retrieved chunks into an LLM. Covers VectorDatabaseQuery(), ListDocumentsInVectorDatabase(), CreateEmbeddingsFromDocuments(), CreateEmbeddingsFromVectorCSVFile(), and RemoveDocumentFromVectorDatabase() pixel commands via @semoss/sdk's runPixel, plus listing engines with MyEngines(engineTypes=["VECTOR"]). Do not use for raw SQL/graph queries (see database-engine) or direct LLM calls without retrieval (see model-engine).