brain-link-discipline

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

29.4k|4.4k|Updated Apr 5, 2026
One-click install
npx skills add https://github.com/garrytan/gbrain --skill brain-link-discipline
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: brain-link-discipline
Source: https://github.com/garrytan/gbrain/tree/main/plugin/skills/brain-link-discipline
Command: npx skills add https://github.com/garrytan/gbrain --skill brain-link-discipline

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 that 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 clickable links before relaying, while keeping links inside brain pages relative so the links/backlinks graph stays intact.
  • Use Case: After committing three new people pages, the agent replies with one verified GitHub URL per page in the same message, or falls back to repo-relative paths and an optional gbrain publish HTML artifact when no hosted remote exists.

Quick Start

Report the brain pages you just created and give me a 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 get a clickable link when an agent commits a brain page?

The link must appear in the same message that reports the commit. The agent derives the repo-relative path with git ls-files --full-name, pushes first, verifies the ref update or remote existence, then outputs the URL as a clickable markdown link.

Why does my brain page link 404 right after the push?

A hosted URL 404s until the push completes and the remote serves the new ref. Confirm the push output shows the ref update before sending the link, or verify the path with an HTTP existence check against the hosted remote's API.

How do I build the correct repo-relative path for a git-hosted file?

Run git ls-files --full-name from the file's directory to get the exact path the remote serves. Never hand-strip your working-directory prefix, since a repo root above your cwd silently drops intermediate segments and produces broken links.

What happens when the brain repo has no hosted remote?

The fallback chain gives the repo-relative path with a note that it is a local path, then offers gbrain publish output as an attachable HTML artifact. The publish output is a local file and must never be presented as a URL.

Should links inside brain pages be absolute URLs or relative paths?

Inside brain pages, use relative markdown links between pages. gbrain's link extraction builds the links/backlinks graph from filesystem-relative links, so absolute URLs between pages are invisible to relational retrieval.

How should subagent results containing local brain paths be relayed?

Rewrite every local path through the same derivation and fallback chain before delivering the subagent's result to the user. Relaying raw local paths verbatim is the most common source of broken link reports.