penguin-sdk
Build AI apps on the Penguin Harness SDK — self-contained projects, the createSession/run streaming loop with thinking and image messages, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.
npx skills add Prism-Shadow/penguin-harness --skill penguin-sdk --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Instructs an agent to build a self-contained Penguin Harness SDK project that runs a streaming createSession/run loop, supports thinking and image messages, and includes a complete RAG knowledge base workflow with BM25 retrieval and a web UI. It uses the Penguin Core SDK to initialize agents, sessions, and data roots, and provides a sample project structure (my-app/) with ingest, rag, and server files for a docs QA workflow.
How it works
- Describes the core concepts: Agent loads state from a dedicated directory, Session represents a conversation inside a Workspace, and session.run() streams thinking, text, and tool calls.
- Shows how to start a session and run a task using session.run([userText(...)], …) with an approve callback gate and optional thinkingLevel overrides.
- Demonstrates how to feed image input alongside text via imageUrlMessage and how to handle thinking streams separately from final text.
- Details the setup flow: install dependencies, configure a model via penguin config model add, and ensure credentials are provided in the app’s local data root, not globally.
- Outlines a default RAG knowledge app: a BM25-based retriever without embeddings, a minimal project structure, and ingest/retrieve scripts (ingest.ts, rag.ts) that process a corpus into data/index.json and a chunk index.
- Provides code snippets for ingesting and retrieving data and defines how to assemble the UI in public/index.html and server.ts for an SSE streaming endpoint.
When to use it
Use when you want a self-contained Penguin Harness-based frontend project that can run a RAG QA app with a web UI, using the default BM25 retrieval and a streaming session loop for user interactions.
What it can touch
- Uses the project’s data root under the current working directory for model configuration and keys (e.g., penguin_data).
- References files and directories within the example app layout (my-app/, corpus/, data/index.json, penguin_data/).
- Invokes Penguin Core via createAgent, createSession, and session.run, with guards for message types.
Caveats
- Emphasizes credential configuration via the app’s key vault and warns against using global ~/.penguin keys for the project.
- The RAG retrieval is BM25-based by default; embeddings require optional upgrades and configuration via additional tooling.
- The example relies on the Penguin Core SDK and repository structure; real deployment requires a functional penguin-core installation and a proper workspace setup.
# Penguin Harness SDK `@prismshadow/penguin-core` is the TypeScript SDK this agent itself runs on. Use it to build your own AI apps: - An **Agent** loads its state (prompts, tools, skills) from `<root>/<project_id>/agents/<agent_id>/`. Creating an Agent whose directory is empty initializes it with defaults. - A **Session** is one conversation of an Agent inside a **Workspace** directory. - `session.run()` executes one task and streams every step (thinking, text, tool calls) as OmniMessages. To have an agent perform a task, use the `run_subagent` tool — the SDK is for building applications, not for invoking agents. ## Before you start If the user's message only invokes this skill (e.g. "use penguin-sdk skill") without a concrete app to build, ask the user what they want to build. But when the request names a concrete goal — even a single sentence like "build a RAG app that answers questions about these docs" — do **not** ask follow-up questions: build it end to end with the defaults in this skill (self-contained workspace project, project default model, BM25 retrieval, web UI styled per the web-design skill) and list the assumptions you made in your final reply. ## Project location
- Before you start
- Project location
- Keys and the data root — check before you build
- Setup
- Streaming loop
- Thinking and image messages
- RAG knowledge app
- Verify before you hand over
env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI)_API_KEY" || echo none npm install @prismshadow/penguin-core tsx git clone --depth 1 <repo_url> corpus/<name> # or curl pages into corpus/ find corpus -type f ! -regex '.*\.\(md\|mdx\|txt\|html?\)$' -delete && rm -rf corpus/*/.git
What does the penguin-sdk skill do?
Build AI apps on the Penguin Harness SDK — self-contained projects, the createSession/run streaming loop with thinking and image messages, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.
How do I install it?
Run `npx skills add Prism-Shadow/penguin-harness --skill penguin-sdk --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From Prism-Shadow/penguin-harness, a repository with 473 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.