brain-link-discipline

When you report a brain page to the user — created, edited, committed, or relayed from a subagent — a working link is part of the deliverable, in the SAME message. Derive the path mechanically (git ls-files --full-name), push BEFORE linking, verify the link resolves when a hosted remote exists, and degrade through a defined fallback chain when it doesn't. Inside brain pages the rule inverts: relative links preserve the link graph; absolute URLs are for chat deliverables only.

Quality

80%

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

85%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 highly actionable, well-sequenced skill body with concrete executable commands, explicit validation checkpoints, and clean one-level-deep navigation. The only meaningful drag is redundancy — the core rules are restated across several sections and could be consolidated to respect the token budget.

Suggestions

Consolidate the repeated 'link is a deliverable / push before link' statements from The rule, Sequence, Contract, and Anti-Patterns into a single canonical statement with cross-references, to reduce redundancy.

Consider trimming the Contract section, which largely restates rules already given in The rule, Sequence, and Scope split — keep only the guarantees not already explicit.

The Anti-Patterns list overlaps heavily with the prose rules; pair each anti-pattern to its governing rule so the section reads as a quick-reference rather than a re-explanation.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and free of basic-concept padding, but the same core rules are restated across The rule, Sequence, Contract, and Anti-Patterns sections (e.g. 'the link is a deliverable, not a follow-up' and 'push before link' each appear several times), which could be tightened.	3 / 5
Actionability	Fully executable guidance throughout: copy-paste bash (`git ls-files --full-name`, `git rev-parse`, the curl verification one-liner), an explicit URL assembly template, and concrete bulk-list and output-format examples covering the common cases.	5 / 5
Workflow Clarity	The push-BEFORE-link sequence is explicitly numbered with validation checkpoints (confirm the ref update, verify 200 before linking) and a feedback path (push-API lag falls back to ref-update evidence), and the fallback chain provides an ordered recovery path.	5 / 5
Progressive Disclosure	No bundle files exist; the body is a single well-sectioned file with one-level-deep, clearly-signaled cross-skill pointers (Dedup section referencing _output-rules.md, brain-first.md, publish, citation-fixer, reports) and easy navigation by section header.	5 / 5
	Total	18 / 20 Passed

Description

76%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 specific, well-scoped description that concretely enumerates the mechanics (derive, push, verify, fallback, inversion) and a clear triggering condition. Its main weakness is that natural user-facing trigger phrases are sequestered in the frontmatter triggers list rather than surfaced in the description prose.

Suggestions

Add an explicit 'Use when ...' clause to the description surfacing natural phrases users say (e.g. 'Use when reporting brain pages you created or edited, or when the user asks for the link / where the page is').

Soften reliance on tool-name jargon ('git ls-files --full-name') in the description in favor of a plain-language action verb so the trigger reads naturally to a non-technical request.

Consider noting the in-page/in-message inversion distinction more briefly in the description, since it is a key differentiator but currently reads as a mechanics aside.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions with comprehensive coverage: 'Derive the path mechanically (git ls-files --full-name)', 'push BEFORE linking', 'verify the link resolves', 'degrade through a defined fallback chain', and the relative-vs-absolute inversion.	5 / 5
Completeness	Answers both 'what' (derive, push, verify, fallback, inversion) and 'when' via the opening 'When you report a brain page to the user — created, edited, committed, or relayed from a subagent', though it stops short of an explicit conventional 'Use when...' trigger clause.	4 / 5
Trigger Term Quality	The description itself leans on technical jargon ('git ls-files --full-name', 'fallback chain', 'link graph') and contains only a couple of natural-ish phrases ('report a brain page', 'working link'); the explicit natural trigger phrases live in the separate frontmatter triggers list rather than the description text.	3 / 5
Distinctiveness Conflict Risk	Occupies a clear niche — outbound brain-page delivery-message link formatting — with distinct triggers and minimal overlap with adjacent skills (publish, citation-fixer, reports), as reinforced by the body's Dedup section.	5 / 5
	Total	17 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 3 suspicious	Warning

	Total	14 / 16 Passed

Repository: garrytan/gbrain
Path: plugin-variants/gbrain-coding/skills/brain-link-discipline/SKILL.md
Commit: 43597b1

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.