repo-architecture

Where new brain files go. Decision protocol for filing brain pages by primary subject, not by format or source. Reference for all brain-writing skills.

Quality

75%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/repo-architecture/SKILL.md

Quality

Content

92%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A tight, actionable, well-sequenced filing skill whose inline content is strong. Its main weakness is progressive disclosure: the detailed rules it points to are not bundled, leaving the most complete guidance unreachable.

Suggestions

Either bundle 'skills/_brain-filing-rules.md' under references/ and link it with a relative path, or inline the essential filing rules so the skill is self-contained.

Convert the 'check if a page already exists' anti-pattern into an explicit numbered validation step in Phases so the verification loop is part of the workflow, not an afterthought.

Resolve the 'skills/conventions/quality.md' notability reference to a bundled file or summarize the notability gate inline.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-paced — a compact contract, a tight decision tree, an output template, and anti-patterns — with no padding or re-explanation of concepts Claude already knows; every section earns its tokens.	3 / 3
Actionability	Concrete, executable guidance: exact path templates ('people/{name-slug}.md', 'companies/{name-slug}.md', etc.), a copy-ready output format string, and named anti-patterns. As an instruction-only skill, the absence of code is not penalized because the guidance is specific and actionable.	3 / 3
Workflow Clarity	The Phases are a clearly sequenced four-step process (identify subject → walk decision tree → cross-link → check notability), with the notability gate and the 'check if a page already exists' anti-pattern serving as validation checkpoints for this low-risk filing task.	3 / 3
Progressive Disclosure	Sections are well organized, but the body defers 'Full filing rules' to 'skills/_brain-filing-rules.md' and the notability gate to 'skills/conventions/quality.md' — neither file is present in the bundle (references/scripts/assets are empty), so the primary detailed material is a dangling reference rather than a clearly signaled, one-level-deep resource.	2 / 3
	Total	11 / 12 Passed

Description

57%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description states a clear, distinctive niche but is light on concrete actions and explicit trigger guidance. It reads as a reference pointer rather than a self-contained capability statement.

Suggestions

Add an explicit 'Use when...' clause naming natural triggers (e.g. 'Use when deciding where a new brain page belongs, or when the user asks where to file a note, person, or meeting').

List one or two more concrete actions (e.g. 'resolves ambiguous filings, suggests a slug and path') to lift specificity from 2 to 3.

Mirror a couple of the frontmatter trigger phrases into the description so natural keywords appear in the scored text, not only in the triggers list.

Dimension	Reasoning	Score
Specificity	Names the domain ('filing brain pages by primary subject, not by format or source') and the core action ('Decision protocol'), but does not enumerate multiple concrete actions the way the level-3 anchor does; it is more of a single-purpose filing rule than a multi-action list.	2 / 3
Completeness	The 'what' is clear ('Where new brain files go... Decision protocol for filing brain pages'), but the description lacks an explicit 'Use when...' clause; the only 'when' signal ('Reference for all brain-writing skills') is weak and implied, capping completeness at 2 per the guideline.	2 / 3
Trigger Term Quality	Relevant keywords appear ('brain files', 'filing', 'brain pages'), but the phrasing leans on 'brain' jargon and lacks common user-spoken variations; the natural trigger phrases ('where does this go', 'filing rules') live in the frontmatter triggers list rather than the description itself.	2 / 3
Distinctiveness Conflict Risk	'Reference for all brain-writing skills' carves out a clear niche (brain-page filing) with distinct triggers, making it unlikely to fire for unrelated skills.	3 / 3
	Total	9 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: garrytan/gbrain
Path: skills/repo-architecture/SKILL.md
Commit: 3fafb69

Reviewed: about 19 hours 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.