worktree-ports

Discover and use stable per-app ports assigned to a local monorepo worktree. Use when starting, opening, testing, or debugging local apps, or when worktree slots, localhost ports, PORT, app URLs, or .worktree-env.json are involved.

Quality

77%

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/worktree-ports/SKILL.md

Quality

Content

65%

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

The body is concise and well-sequenced with concrete commands, but several configuration directives lack the example structure that would make them fully executable, and a relevant bundle file (the schema) is not referenced. Adding a config example and a validation checkpoint would raise the weaker dimensions.

Suggestions

Add a small .worktree-env.json example (or link to assets/worktree-env.schema.json) so the 'exports', 'offset', and 'range stride' directives are concrete and copy-paste ready.

Name the specific scripts in scripts/ (e.g. worktree-runtime.ts) rather than pointing generically to the directory, improving navigation.

Add a validation checkpoint after 'bun dev:info --json' (e.g. verify the returned URL's port is free before starting the app) to close the workflow-clarity gap.

Dimension	Reasoning	Score
Conciseness	Seven lean bullets with no explanation of concepts Claude already knows (ports, worktrees, env files); every directive earns its place, matching the 'lean and efficient' anchor.	3 / 3
Actionability	Provides concrete commands and file names ('bun dev:info --json', '{apps.<name>.url}', '.worktree-env.json'), but config-editing bullets like 'Declare every variable an app needs under its exports' and 'Keep app offsets unique' lack the example structure needed to be copy-paste ready.	2 / 3
Workflow Clarity	A clear 'before'-ordered sequence exists ('Run bun dev:info --json before accessing local apps', 'loaded before the wrapper runs'), but there are no explicit validation checkpoints or error-recovery feedback loops.	2 / 3
Progressive Disclosure	The body is a clean overview with a signaled one-level reference to scripts/, but it instructs on .worktree-env.json structure without pointing to the existing assets/worktree-env.schema.json, and the script reference is generic rather than file-named.	2 / 3
	Total	9 / 12 Passed

Description

90%

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: third-person, specific domain, explicit 'Use when' triggers covering natural user phrasing, and a distinctive niche. Its only weakness is that the action list ('Discover and use') is brief rather than comprehensive.

Dimension	Reasoning	Score
Specificity	Names the domain and two concrete actions ('Discover and use stable per-app ports assigned to a local monorepo worktree'), matching the score-2 anchor's two-action pattern; not a comprehensive list of multiple distinct actions, so it is not a 3.	2 / 3
Completeness	Clearly states what it does ('Discover and use stable per-app ports...') and provides an explicit 'Use when...' clause with multiple triggers, answering both what and when.	3 / 3
Trigger Term Quality	Covers natural terms a user would say — 'starting, opening, testing, or debugging local apps' plus 'localhost ports, PORT, app URLs' — giving good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	The worktree-port-slot niche is narrow and its triggers (e.g. '.worktree-env.json', 'worktree slots') are distinctive, making conflict with other skills unlikely.	3 / 3
	Total	11 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: FranciscoMoretti/chat-js
Path: .agents/skills/worktree-ports/SKILL.md
Commit: f66626f

Reviewed: 1 day 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.