workspace-conventions

Shared conventions for a multi-app Agent-Native workspace: finding version-matched framework docs and source, shared vs app-owned code, file and blob storage, env and secrets, agent scratch files, and Dispatch Resources. Use when working across workspace apps, storing files or credentials, or looking up framework APIs.

Quality

86%

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

Quality

Content

78%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.

A dense, convention-style skill that stays workspace-specific on every line, names exact APIs, paths, and config shapes, and uses a clean one-level-deep Related Skills index for detail. Its weakness is compression of several rules into long stacked-clause bullets, which hurts readability more than token efficiency.

Suggestions

Split the long stacked-clause bullets (the agent-chat rules and the builtinAgents config rules) into separate short rules so each constraint is scannable.

Specify where agent_scratch resources are created or point to the skill/command that manages them, since the bullet currently references the concept without a location.

Move the detailed builtinAgents JSON shape into the referenced skill (e.g., adding-workspace-apps) and keep only the rule plus pointer here.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's competence throughout — no basic-concept explanations, every rule is workspace-specific. A few bullets stack many clauses into single sentences (the AI-chat bullet and the builtinAgents bullet) and could be trimmed or split. That keeps it at 'efficient with minor instances that could be tightened' rather than anchor 5.	4 / 5
Actionability	Guidance is concrete: exact function names ("sendToAgentChat()", "useAgentChatContext"), exact paths ("packages/shared", "apps/<app>/.env"), and an exact config schema ("agent-native.builtinAgents" with its mode/include shape). As an instruction/conventions skill, absence of code is not penalized; minor gaps remain — e.g., where agent_scratch resources are created and how "Dispatch Resources" are accessed are left unspecified, deferring to other skills.	4 / 5
Workflow Clarity	Not a multi-step process skill; it is a conventions index. The sequences it does prescribe are clearly ordered with fallbacks ("framework-search first, then the focused docs-search/source-search readers, and the rg fallback"; the "configure → compose → eject the smallest unit" ladder), and no destructive or batch operations lack validation. Minor gaps: the lookup and customization workflows' remaining steps live in the referenced skills, so checkpoints are only implied here.	4 / 5
Progressive Disclosure	The body is a clear overview: three well-organized sections with a Related Skills index giving one-line descriptions per skill ("agent-native-docs — The full docs and source-corpus lookup workflow"), matching the good-example pattern. All references are one level deep and clearly signaled in place ("Read `agent-native-docs` for the lookup workflow", "read .agents/skills/performance/SKILL.md §9"); no bundle files exist to nest.	5 / 5
	Total	17 / 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 that states what the skill covers in specific terms and gives an explicit, natural 'Use when' trigger clause. Third-person voice is correct and there is no fluff. Only weakness is modest synonym coverage in the trigger terms.

Suggestions

Add one or two natural synonyms to the trigger clause, e.g. 'storing files, credentials, or API keys' or 'looking up framework APIs or package docs'.

Dimension	Reasoning	Score
Specificity	The description enumerates the skill's concrete coverage comprehensively — "finding version-matched framework docs and source, shared vs app-owned code, file and blob storage, env and secrets, agent scratch files, and Dispatch Resources" — mapping one-to-one to the body's scope. Nothing is generic padding.	5 / 5
Completeness	Both halves are explicit: the "what" ("Shared conventions for a multi-app Agent-Native workspace: ...") and the "when" ("Use when working across workspace apps, storing files or credentials, or looking up framework APIs"). This matches the anchor-5 example structure exactly.	5 / 5
Trigger Term Quality	Natural phrases like "working across workspace apps", "storing files or credentials", and "looking up framework APIs" mirror what a user would say. Coverage is good but misses common synonyms such as "secrets", "API keys", ".env", or "blob storage" that appear in the body.	4 / 5
Distinctiveness Conflict Risk	Distinctive niche markers ("Agent-Native workspace", "Dispatch Resources", "agent scratch files") and a cross-app trigger keep it clearly distinguishable. Minor overlap risk with closely related skills it indexes (secrets, storing-data) since it mentions "env and secrets" and "file and blob storage".	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/workspace-conventions/SKILL.md
Commit: a941a2e

Reviewed: 2 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.