adding-workspace-apps

How to add an app to an Agent-Native workspace: classifying an "agent" request, scaffolding `apps/<app-name>`, app discovery and descriptions, mounting and base paths, action-first data, and finishing a chat-template app. Use when asked to create, build, scaffold, or generate a new agent or app in a workspace.

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/adding-workspace-apps/SKILL.md

Quality

Content

68%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a lean, well-structured overview with concrete commands and specific API/file references that mostly assume Claude's competence. Its main weakness is workflow clarity: the scaffold-to-finish flow lacks explicit validation checkpoints, and some content could be offloaded to reference files.

Suggestions

Add an explicit verification checkpoint in the Scaffolding and Finishing sections (e.g. 'After scaffolding, confirm the app appears under `pnpm dev` before branding it') to close the validation gap that caps workflow_clarity.

Provide one copy-paste-ready `defineAction` example with the `http: { method: "GET" }` read marker so the actions guidance is fully executable rather than identifier-only.

Move the PostgreSQL detail block into a `references/db.md` file referenced from the body, tightening the overview and strengthening progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence — it does not explain what Postgres, React Router, or shadcn are, and uses concrete identifiers like `defineAction`, `APP_BASE_PATH`, and `appBasePath()`. It is not a 5 because a few rationale sentences (e.g. "Action-backed UI is what makes agent-created or agent-edited records appear without a manual refresh") could be trimmed.	4 / 5
Actionability	It gives concrete, executable guidance — `pnpm exec agent-native create <app-name> --template=<template>`, `http: { method: "GET" }`, `useActionQuery`/`useActionMutation`, and specific file paths like `app/entry.client.tsx`. It is not a 5 because guidance is instruction-style with identifiers rather than complete copy-paste code blocks, and some directives ("Keep raw SQL for additive migrations") are descriptive rather than executable.	4 / 5
Workflow Clarity	Sections are sequenced as a logical flow (classify → locate → vault → discovery/UI → actions → DB → scaffold → finish) with a classification decision gate and a finishing do-not checklist. It is not a 4 because explicit validation/verification checkpoints in the scaffold→finish path are mostly implicit — there is no validate-then-proceed step for the DB or scaffolding work.	3 / 5
Progressive Disclosure	The body is a well-organized overview split into clearly headed sections, with one-level-deep pointers ("Read `.agents/skills/shadcn-ui/SKILL.md`" and a Related Skills list) for detail. It is not a 5 because at ~95 lines it exceeds the simple-skill threshold and relies on inline prose rather than a bundle-file split for some content that could live in references.	4 / 5
	Total	15 / 20 Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it states what the skill does through several concrete actions and gives an explicit 'Use when...' trigger clause with natural verbs. The only weaknesses are a couple of missing trigger synonyms and minor overlap with related workspace skills.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "classifying an 'agent' request, scaffolding `apps/<app-name>`, app discovery and descriptions, mounting and base paths, action-first data, and finishing a chat-template app" — giving comprehensive coverage comparable to the score-5 anchor. It is not a 4 because the action list is broad and specific rather than having only minor gaps.	5 / 5
Completeness	It explicitly answers both what ("How to add an app to an Agent-Native workspace: classifying... scaffolding... finishing a chat-template app") and when ("Use when asked to create, build, scaffold, or generate a new agent or app") with concrete trigger phrases, matching the score-5 anchor. It is not a 4 because the 'when' is explicit and specific rather than merely present.	5 / 5
Trigger Term Quality	The trigger clause "Use when asked to create, build, scaffold, or generate a new agent or app in a workspace" plus "add an app" gives good natural-verb coverage a user would say. It is not a 5 because a few natural synonyms (e.g. "make") are absent and there are no domain-specific file-extension triggers.	4 / 5
Distinctiveness Conflict Risk	The "Agent-Native workspace" + "new agent or app" framing carves a clear niche with distinct triggers, but it shares scope with closely related sibling skills (workspace-conventions, actions, composable-mini-apps), giving minor overlap risk. It is not a 5 because of that sibling-skill overlap, and not a 3 because the triggers are clearly workspace-app-specific.	4 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: BuilderIO/agent-native
Path: .agents/skills/adding-workspace-apps/SKILL.md
Commit: b0df876

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.