Guide · Agent skill
How to use the Repo Architecture Filing Rules agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The repo-architecture skill gives an AI agent a set of filing rules for a personal knowledge base, a 'brain' made of markdown pages. When you ask the agent to create a new page, it works out the page's main subject and places it in the matching folder, such as people, companies, concepts or meetings. This guide explains what the skill does, how to install it, how to trigger it, and where its limits are.
Repo Architecture Filing Rulesgarrytan/gbrain · MIT Download the skill Quick start
- 1Download the ZIP. Download the repo-architecture skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm your gbrain tools are available. Make sure your gbrain knowledge base provides search, get_page and list_pages, and that the repository includes the two rules files.
- 5Ask a filing question. Describe the page in plain language and use a trigger phrase such as where does this go.
- 6Make the change yourself. Review the recommended path and create or move the file yourself, since the skill only advises.
What is an agent skill, and what does this one do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. This skill covers one job: deciding where a new brain page belongs.
Instead of sorting files by format (such as PDF) or by where they came from (such as email), the agent identifies the primary subject of the page and files it by that subject. It also checks whether a page already exists and suggests cross-links to related directories.
- Asks: what would you search for to find this page?
- Maps the subject to a folder: people/, companies/, concepts/, originals/, meetings/, media/{type}/ or sources/
- Checks notability against the quality conventions before filing
- Reports its advice in the form: File this at {type}/{slug}.md because the primary subject is {reason}.
Install the repo-architecture skill
Download the skill ZIP from this page. Then choose one of the two install routes below.
For Claude Code, unzip the file into ~/.claude/skills/ to make it available across all your projects, or into a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you rely on it
The skill is built for a gbrain knowledge base. It needs that knowledge base to provide search, get_page and list_pages tools for live lookups. It also needs access to two files in the repository: skills/_brain-filing-rules.md and skills/conventions/quality.md.
The skill's folder rules are specific to gbrain. They will not apply to a different note system. It does not run scripts and does not use the network.
- gbrain knowledge base with search, get_page and list_pages tools
- Access to skills/_brain-filing-rules.md and skills/conventions/quality.md in the repository
- Runs scripts: no
- Uses network: no
How to trigger the skill with natural requests
The skill activates when your request matches its trigger phrases. You do not need to type a command. Ask in plain language and include the page you want to file.
The skill's triggers are: "where does this go", "filing rules", "create new page" and "which directory".
- Where does this go? This is a meeting summary with Priya from Tuesday.
- Create new page for Acme Robotics, a company I met last week.
- Which directory should a PDF of our pricing research go in?
- What are the filing rules for a concept page about event sourcing?
What the agent does with your request
The skill follows four phases. First it identifies the primary subject. Then it walks a decision tree that maps subjects to folders. Next it cross-links from related directories, and finally it checks notability.
The decision tree sends a person to people/{name-slug}.md, a company to companies/{name-slug}.md, a reusable concept or framework to concepts/{slug}.md, an original idea to originals/{slug}.md, a meeting to meetings/{slug}.md, media content to media/{type}/{slug}.md, and raw data import to sources/{slug}.md.
- Phase 1: Identify the primary subject
- Phase 2: Walk the decision tree
- Phase 3: Cross-link related directories
- Phase 4: Check notability against skills/conventions/quality.md
Know what the skill will not do
The skill only advises. Its file declares mutating: false, so it does not write, move or delete files. You or your agent must make the change based on its advice.
If the live brain is unreachable, or search and list_pages cannot find a matching directory, the skill falls back to the offline rules in skills/_brain-filing-rules.md. In that case it says the placement came from the rules, not the live brain, and placement may be less accurate. If get_page returns page_not_found for the page being filed, the skill asks you to confirm the slug before choosing a directory.
- Does not create, edit or move files itself
- Falls back to offline rules when the brain cannot be reached
- Asks you to confirm the slug when a page is not found
- Avoids filing by format or source, and avoids creating duplicate pages
What people use it for
- Deciding whether a meeting summary belongs in meetings/ or under the person's page in people/
- Filing a new company profile in companies/ after checking for an existing page
- Keeping raw data dumps in sources/ and out of other folders
- Getting cross-link suggestions when adding a new concept page
- Onboarding teammates to one shared filing convention for an agent-driven note system
Frequently asked questions
How do I install the repo-architecture skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What do I need to use the repo-architecture skill?
You need a gbrain knowledge base that provides search, get_page and list_pages tools, plus access to skills/_brain-filing-rules.md and skills/conventions/quality.md in the repository. The skill does not run scripts and does not use the network.
Is the repo-architecture skill free?
The source lists the skill's licence as MIT. Check the repository's licence file for the full terms before you use or redistribute it.
Does the skill move or create files for me?
No. The skill declares mutating: false and only gives placement advice. You need to create or move the file yourself based on its recommendation.
What happens if the skill cannot reach my brain?
It falls back to the offline rules in skills/_brain-filing-rules.md and tells you the placement came from the rules, not the live brain. Placement may be less accurate in that case.
Can I use this skill with a note system other than gbrain?
The folder rules are specific to gbrain-style markdown knowledge bases, so they will not apply to other systems. It is designed for gbrain setups.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain a gbrain-style markdown knowledge base and want new pages filed consistently by primary subject, or if your team runs agent-driven notes and needs one shared convention. Skip it if you do not use gbrain, if you expect the skill to write or move files, or if you need a live check of the brain that the offline fallback cannot provide.
Download the skill