Cohub work kit

Cohub Work Kit

Create or evolve a Cohub Work product from the kit template bundled with this skill.

Install this skill

npx skills add https://github.com/markbang/cohub-work-skill \
  --skill "cohub-work-kit" \
  --agent codex \
  --yes \
  --copy

Also install the publish companion:

npx skills add https://github.com/markbang/cohub-work-skill \
  --skill "cohub-work-publish" \
  --agent codex \
  --yes \
  --copy

When to use

• User wants a new Cohub Work app / product shell
• User mentions Work Kit, Vite Work, React Work, or TanStack Query + Cohub
• User wants files / sessions / prompt / commerce inside a published Work

Locate the template

This skill ships the template inside the installed skill directory:

.agents/skills/cohub-work-kit/template/

In a git checkout of this repo:

skills/cohub-work-kit/template/

If this kit is mounted as a Cohub mod instead:

/mods/<mountSlug>/template

Resolve the real template/ path before copying. Do not invent paths.

Default outcome

apps/<product-slug>/
  src/lib/*            # keep
  src/pages/*          # replace with product UI
  package.json
  vite.config.ts       # base: "./"

Workflow

1. Confirm product boundary

Pin:

• product name / Work slug
• reads (file.view, session.view, space.view)
• writes / agent / commerce (viewer scopes)
• non-goals for this pass

2. Copy template

SKILL_DIR=".agents/skills/cohub-work-kit"   # after npx skills install
# or: SKILL_DIR="skills/cohub-work-kit"     # repo checkout

src_template="$SKILL_DIR/template"
dest="apps/<product-slug>"

mkdir -p "$(dirname "$dest")"
cp -a "$src_template"/. "$dest"/

3. Preserve the runtime seam

Do not casually edit unless required:

• src/lib/runtime.tsx
• src/lib/query.ts
• src/lib/hooks.ts
• vite.config.ts (base: "./")
• HashRouter in src/App.tsx

Product work belongs in src/pages/*, src/components/*, optional src/features/*.

3b. Viewer identity (Cohub avatar + id)

The shell top-right uses useViewerProfile() (client.user.getMe()), same pattern as wgetx social-asset-pool:

• shows avatar + displayName / @username
• click opens panel with full userUuid + copy
• do not rely on context.viewer alone (often null)

import { useViewerProfile } from "./lib";
const me = useViewerProfile();
// me.data?.userUuid / avatarUrl / displayName

4. Implement product reads with Query

const tree = useFileTreeQuery("data");
const file = useFileContentQuery("data/feed.json");
const sessions = useSessionsQuery(10);

Rules:

• enable queries only when runtime status is ready
• 401/403/404 should not infinite-retry
• mutable source-of-truth lives in Space files / sessions / billing, not in dist

5. Writes = user gesture + scopes

await client.auth.request({
  scopes: ["session.prompt.fullaccess"],
  reason: "Need to run an agent action for this product feature",
});
await space.prompt({ /* ... */ });
// invalidate related queries

Never authorize on mount. Never invent a parallel login system.

6. Routing constraints

• HashRouter paths (#/settings)
• no BrowserRouter for static directory Works
• relative asset base (./)

7. Permissions at publish time

Start minimal:

--work-scope file.view

Add viewer scopes only for actions the UI actually offers.

8. Verify

cd apps/<product-slug>
pnpm install
pnpm build

Then publish with the cohub-work-publish skill and open the public Work URL.

Product patterns

File-backed app

files.read → render
user edit intent → auth → prompt/agent writes file → refresh

Agent console

sessions.list → select → prompt(followup) → stream/poll

Commerce gate

getEntitlements → gate UI → purchase/consumeCredits → revalidate

Anti-patterns

• Rebuilding Cohub auth inside the Work
• Baking live business data into static publish output
• Port Work as default production
• Broad full-access scopes "just in case"
• Deep History API routes on static directory hosting

Done criteria

• Template copied into consumer workspace
• Product UI mounted on kit runtime
• Build succeeds
• Publish scopes match actual features
• Public Work boots to ready (or intentional preview fallback documented)