x-upstream

Use when the user wants to vendor or track an upstream GitHub repo as a research reference inside the current project — adds, updates, lists, or removes `research/<owner>/<repo>` git submodules pinned to the latest stable release (not main/HEAD). Invoked for upstream code reference, dependency mirroring, or research material management.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

92%

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

A tight, highly actionable reference for a self-contained shell-wrapper skill — executable commands, clear sequencing, and explicit failure handling. The one gap is a dangling `gotchas.md` reference that has no corresponding bundle file.

Suggestions

Either add a `gotchas.md` file to the bundle or remove the "See `gotchas.md`" line so all referenced files resolve.

If `../x-shared/capability-loading.md` is a peer-skill file outside this bundle, note that explicitly so the cross-bundle reference is not mistaken for a missing local file.

Dimension	Reasoning	Score
Conciseness	Lean throughout — a command table, terse dispatch examples, and a detection spec with no padding or explanation of git/gh/submodule concepts Claude already knows; every line earns its place.	3 / 3
Actionability	Provides copy-paste-ready `bash $SKILL_DIR/scripts/x-upstream.sh ...` commands, an exact command-behavior table, and a concrete stable-detection spec with real `gh`/`git ls-remote` invocations and the precise semver regex.	3 / 3
Workflow Clarity	Sequenced bootstrap with prerequisites, a scripted multi-step flow that `cd`s to the repo root, explicit failure handling (add aborts / update skips with a warning), and a caller validation checkpoint (staged-but-uncommitted with `git diff --cached` review).	3 / 3
Progressive Disclosure	Well-organized sections with the bulk of logic correctly delegated to the real `scripts/x-upstream.sh`, but the body references `gotchas.md` ("See `gotchas.md` for known failure patterns") which is not present in the bundle, so a one-level reference does not resolve.	2 / 3
	Total	11 / 12 Passed

Description

85%

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, specific description with an explicit Use-when clause and concrete enumerated actions. Its only weakness is trigger-term naturalness — the phrasings skew technical rather than mirroring how a user would request this.

Suggestions

Add more user-natural trigger phrasings (e.g., "keep a local copy of a repo for reference", "mirror a dependency for offline lookup") alongside the technical terms.

Consider dropping or softening jargon like "git submodules" in the opening clause so the trigger reads as a user need before the mechanism.

Dimension	Reasoning	Score
Specificity	Names the domain and four concrete actions ("adds, updates, lists, or removes `research/<owner>/<repo>` git submodules") plus the stable-tag pinning constraint and exact path convention — multiple specific concrete actions.	3 / 3
Completeness	Opens with an explicit "Use when the user wants to vendor or track..." trigger and lists what it does (adds/updates/lists/removes submodules pinned to the latest stable tag), answering both what and when.	3 / 3
Trigger Term Quality	Has relevant terms ("vendor upstream", "track upstream", "upstream code reference") but leans technical ("git submodules", "stable release") and misses the more natural phrasings a user would actually say; coverage of common variations is partial.	2 / 3
Distinctiveness Conflict Risk	Occupies a clear niche (vendoring upstream repos as read-only stable-tagged submodules under `research/`) with specific triggers unlikely to overlap with generic git or package-manager skills.	3 / 3
	Total	11 / 12 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: quangtran88/x-skills
Commit: 6381b15

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.