How to use the Brain Link Discipline agent skill

What the skill makes the agent do

The skill governs how an agent reports brain pages. When it creates, edits, or commits a page, or relays a subagent result that mentions a brain path, the link must appear in the same message as the report. The skill also tells the agent how to build the correct path from the git repository root, and, when a hosted remote exists, to check the link resolves before sending it.

Inside brain pages the rule reverses. The skill asks for relative links such as [Alice Example](../people/alice-example.md), because gbrain builds its link and backlink graph from filesystem-relative links. Absolute URLs are for chat messages only.

• Pushes the page before linking, so the URL does not 404.
• Derives the exact repo-relative path with git ls-files --full-name instead of guessing.
• Verifies the link on a hosted remote when possible, and falls back to a repo-relative path or an HTML artifact when it is not.

Install the skill (ZIP download or Claude apps upload)

Download the ZIP from the skill's page on this directory and unzip it. The skill's files include SKILL.md. For a personal install, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps by going to Settings → Capabilities → Skills and adding the ZIP there.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill is triggered by requests that match its listed phrases. Asking in ordinary language works, as long as the request is about getting a link to a brain page.

• "Give me the link"
• "Where is the page?"
• "Why does this link 404?"
• "Send me a clickable link"
• "Report the pages you created"
• "Rewrite subagent paths"

Set up the brain repository and optional token

The skill needs git and a brain repository with a git remote. The source names gbrain's checkout and scripts/brain-commit-push.sh, or the gbrain CLI, as examples. Without a git-backed brain there is nothing for the path and push steps to act on.

A GITHUB_TOKEN environment variable is optional. It lets the skill verify links on private GitHub repositories. Without it, verification of private repos will fail and the fallback chain applies. Network access to the hosted git host is also optional and is only needed for link verification.

• Required: git and a brain repo with a git remote
• Optional: GITHUB_TOKEN for verifying links on private GitHub repos
• Optional: network access to the git host for verification

Example: a page is created and reported with a link

Suppose you ask your agent to write a page about a person. The agent writes the file, then commits and pushes only that file with scripts/brain-commit-push.sh. It derives the path with git ls-files --full-name and assembles the URL from the remote and branch. Once the push output confirms it landed, the agent puts the clickable link in the same reply.

If the push fails with a non-zero exit, the skill says to output no link. It retries once on commit_lock_busy, and stops and tells you on integrate_conflict or writer_coordinator_required.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The verification step makes an HTTP request to the remote host. The source says the Authorization token header targets api.github.com for github.com remotes and must never be sent to any other host derived from git remote get-url origin without confirming it is the token's issuing host.

For a non-GitHub remote, the skill says to verify unauthenticated or skip verification and rely on the push output. When in doubt, the skill says not to send the token. The skill is also a reporting convention, not an enforced guarantee, so review the agent's output if links matter.

• Only send GITHUB_TOKEN to api.github.com for github.com remotes.
• Check the remote host before trusting origin.
• Treat the skill as guidance the agent follows, not a tool-enforced rule.

Tips for reliable links

Always derive paths from the git repo root, not from your working directory, because stripping the cwd prefix by hand drops segments and causes 404s. Use /blob/ for files and /tree/ for directories on GitHub-style hosts. Inside brain pages, keep page-to-page links relative.

If the brain has no hosted remote, expect the repo-relative path plus a note that it is local. For sensitive content, the gbrain publish command can produce a local HTML file; the source says to use --password for that.

• Use git rev-parse --show-toplevel to confirm the repo root.
• Link files with /blob/ and directories with /tree/.
• For sensitive pages, use gbrain publish with --password.