brain-link-discipline

Generates verified clickable links for brain pages in delivery messages using git-derived paths.

Updated Aug 17, 2026
One-click install
npx skills add https://github.com/AMC-JTC/gbrain-1 --skill brain-link-discipline-amc-jtc
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: brain-link-discipline
Source: https://github.com/AMC-JTC/gbrain-1/tree/main/plugin/skills/brain-link-discipline
Command: npx skills add https://github.com/AMC-JTC/gbrain-1 --skill brain-link-discipline-amc-jtc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an agent commits and pushes a brain page, users often receive a report with no link, a broken link, or a raw local path they cannot click. This Skill enforces a reporting discipline where every message that reports a created, edited, or relayed brain page includes a working link in the same message, derived mechanically from git data rather than guessed. ## Core Features & Use Cases - Mechanical path derivation: Builds repo-relative paths with git ls-files --full-name and assembles hosted URLs from git remote get-url origin, eliminating hand-stripped prefixes that cause 404s. - Push-before-link ordering with verification: Requires the push to land and the ref update to be confirmed (or an HTTP existence check against the hosted remote) before any URL is sent, with a defined fallback chain for local-only repos. - Subagent relay rewriting and scope split: Rewrites local paths returned by subagents into user-facing links, and enforces the inversion rule — relative links inside brain pages to preserve the links/backlinks graph, absolute verified URLs only in chat messages. - Use Case: After committing three new people pages, the agent replies in the same message with one verified GitHub link per page, or falls back to repo-relative paths plus a gbrain publish HTML artifact offer when no hosted remote exists. ## Quick Start Report the brain pages you just committed and include a working clickable link for each one in the same message.

Frequently Asked Questions about brain-link-discipline

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a correct GitHub link for a committed file?

Derive the repo-relative path with git ls-files --full-name from the file's directory, then assemble https://<host>/<owner>/<repo>/blob/<branch>/<path> using git remote get-url origin and the current branch. Never hand-strip your working directory prefix, since that drops intermediate path segments.

Why does my link 404 right after pushing a page?

A hosted URL 404s until the push completes, so confirm the push output shows the ref update before sending the link. You can also verify with an HTTP existence check against the host API and only send the link on a 200 response.

Should brain pages link to each other with absolute URLs?

No. Inside brain page bodies, use relative markdown links like [Alice](../people/alice-example.md) because the link extraction that builds the links/backlinks graph only reads filesystem-relative links. Absolute URLs are reserved for chat deliverables and genuinely external targets.

What should I do when the brain repo has no hosted remote?

Fall back to giving the repo-relative path with a plain note that it is a local path in the brain repo. For shareable output, run gbrain publish to produce a self-contained local HTML file and offer it as an attachable artifact, never as a URL.

How do I handle local paths returned by subagents?

Rewrite every brain-page path in a subagent's completion through the same git-based derivation and fallback chain before relaying it to the user. Relaying raw local paths verbatim is the most common source of broken link reports.