merge-upstream-vscode

This skill should be used when merging upstream changes from vscode-server into the Positron IDE repository. Invoke it when the git repository contains the conflicted changes from an upstream merge.

Quality

83%

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

92%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 high-quality, deeply actionable merge runbook with a clear multi-step workflow, explicit validation/feedback loops, and well-organized one-level-deep references to real bundle files. The only minor weakness is occasional prose restating what the preceding example already shows.

Suggestions

Tighten the explanatory paragraphs immediately following each conflict example, since the example plus a single sentence would convey the same resolution rule with fewer tokens.

Dimension	Reasoning	Score
Conciseness	The body is dense with domain-specific knowledge Claude would not already know (PWB patches, npm ci lockfile failure modes, test-tag-map mechanics) and avoids restating basics; only minor stretches could be trimmed. It sits above 3 (which tolerates unnecessary explanation) but short of 5 (every token earns its place) because some prose around the examples restates the obvious.	4 / 5
Actionability	Provides copy-paste-ready, specific commands for every phase (npm install / npm ci / npm install --package-lock-only, cd build && npm run typecheck, build-stop/build-start/build-check, test:core, the pr-tags-lib.sh invocation) plus concrete conflict-resolution examples. Fully executable across the common cases, matching the top anchor rather than 4's 'minor gaps'.	5 / 5
Workflow Clarity	An explicit 8-step sequence (Review -> Resolve -> Install -> Compile -> Test -> Tag map -> Document -> Final tests) with validation checkpoints and feedback loops throughout (run npm ci until it passes, regenerate lockfile then re-verify, daemons must report 0 errors, do not push with core Mocha unrun). This matches the top anchor with explicit validation and error-recovery loops, well above 4.	5 / 5
Progressive Disclosure	SKILL.md is an overview with clearly signaled one-level-deep references to real bundle files (change-markers.md, package-json.md, codicons.md), all of which exist in ./references/, and detailed sub-knowledge is appropriately split out. Easy navigation with no nested-reference chains, matching the top anchor.	5 / 5
	Total	19 / 20 Passed

Description

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

The description is precise and distinctive, explicitly covering both what the skill does and when to invoke it with concrete trigger guidance in third person. Trigger-term coverage and the breadth of enumerated actions are the weakest points but still adequate.

Suggestions

Broaden trigger terms to include natural user phrasing like 'merge conflict', 'resolve conflicts', or 'cherry-pick' so the description matches how users actually ask for help.

List a few more concrete actions (e.g. reapply Positron change markers, regenerate package-lock.json, run npm ci) to lift specificity from adequate to comprehensive.

Dimension	Reasoning	Score
Specificity	Names the domain ('merging upstream changes from vscode-server into the Positron IDE repository') and a couple of concrete actions ('resolve the conflicts', 'compiles cleanly and passes tests'), but the action set is not comprehensively enumerated. It is above 2 (which would only name the domain) but below 4 (which lists several specific actions).	3 / 5
Completeness	Explicitly answers both 'what' ('merging upstream changes from vscode-server into the Positron IDE repository' and resolving conflicts until compile/tests pass) and 'when' ('Invoke it when the git repository contains the conflicted changes from an upstream merge') with concrete trigger phrasing, in third person. Clearly meets the top anchor rather than the 4 anchor whose 'when' is less explicit.	5 / 5
Trigger Term Quality	Contains relevant phrases a user might say ('merging upstream changes', 'upstream merge', 'conflicted changes') but is missing common natural variations and synonyms a user would reach for first (e.g. 'merge conflict', 'resolve conflicts', 'cherry-pick'). Good but not comprehensive, so a 3 rather than 4.	3 / 5
Distinctiveness Conflict Risk	A clear niche tied to a specific named repository pair (vscode-server -> Positron IDE) with distinct triggers; minimal realistic conflict risk with other skills. Fits the top anchor better than 4's 'minor overlap risk'.	5 / 5
	Total	16 / 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
referenced_paths_exist	Referenced path issues: 5 missing, 1 deeper-than-1-level	Warning

	Total	15 / 16 Passed

Repository: posit-dev/positron
Path: .claude/skills/merge-upstream-vscode/SKILL.md
Commit: b0258bc

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.