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

84%

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

76%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 well-organized, highly actionable body with executable commands and clear structure. Its main weakness is workflow clarity for batch/destructive operations, where explicit validation feedback loops in the markdown would lift it above the cap.

Suggestions

Add an explicit validation checkpoint before staging/committing for `update all` and `remove` (e.g. 'after `update all`, run `git submodule status` and confirm each pinned tag before committing') to satisfy the batch/destructive feedback-loop requirement.

Create the referenced `gotchas.md` (or inline its key failure patterns) so the 'See gotchas.md' pointer resolves to a real file in the bundle.

Trim contextual prose such as the capability-loading bootstrap note and 'without depending on the upstream remote at runtime' to tighten token efficiency.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with table-driven commands and executable examples and no concept lessons, but a few phrases (e.g. 'without depending on the upstream remote at runtime', the capability-loading bootstrap note) could be trimmed.	4 / 5
Actionability	Provides copy-paste-ready `bash $SKILL_DIR/scripts/x-upstream.sh ...` invocations covering every command, a precise command/flag table, the stable-detection algorithm, and examples with expected output.	5 / 5
Workflow Clarity	Sequencing and script-internal validation exist (rollback, init-check, path-safety refuse, staged-not-committed review), but this batch/destructive skill lacks explicit validate->fix->retry checkpoints in the markdown body, capping it per the rubric.	3 / 5
Progressive Disclosure	Well-structured overview with one-level-deep references to scripts/x-upstream.sh (present) and clearly signaled sections; `gotchas.md` and `../x-shared/capability-loading.md` are referenced but not part of the bundle, a minor gap.	4 / 5
	Total	16 / 20 Passed

Description

92%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, specific description that states both what the skill does and when to use it, with concrete actions and a distinct niche. Trigger-term coverage is good but could add a few more natural synonyms.

Dimension	Reasoning	Score
Specificity	Names four concrete actions ('adds, updates, lists, or removes `research/<owner>/<repo>` git submodules pinned to the latest stable release') plus the stable-tag constraint, giving comprehensive concrete coverage.	5 / 5
Completeness	Explicitly answers both 'what' (the four submodule operations and pinning rule) and 'when' ('Use when the user wants to vendor or track...'; 'Invoked for upstream code reference, dependency mirroring, or research material management').	5 / 5
Trigger Term Quality	Natural user phrases like 'vendor', 'track upstream', 'dependency mirroring', and 'research material management' are present, but obvious synonyms/extensions (e.g. 'vendor dependency', 'add repo') are missing.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (research submodules pinned to stable tags under research/<owner>/<repo>) with distinct triggers, making conflict with other skills minimal.	5 / 5
	Total	19 / 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: quangtran88/x-skills
Path: skills/x-upstream/SKILL.md
Commit: f17a69e

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