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

64%

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

78%Weight 40%Scale 1-5

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

A lean, well-structured instruction-only skill: the decision tree, output template, and anti-patterns are concrete and the body respects the token budget completely. Its main weakness is that it delegates its core content (full filing rules, notability gate) to files that are not part of the skill bundle, leaving those references dangling and the guidance partially incomplete.

Suggestions

Ship the referenced files inside the skill bundle (e.g. `references/filing-rules.md`, `references/notability.md`) or inline the essential criteria — especially the notability gate — so the dangling `skills/...` paths don't break progressive disclosure.

Add an explicit verify step to the phases (e.g. confirm no existing page covers the subject before creating a new one) to make the existing implicit checkpoints explicit.

State the notability threshold inline in step 4, or at least one line summarizing what the gate checks, since users of the skill cannot currently act on 'See quality.md notability gate'.

Dimension	Reasoning	Score
Conciseness	The ~35-line body is lean with zero padding or concept explanations — the decision tree ("About a person → `people/{name-slug}.md`"), output template, and anti-patterns each earn their tokens. Matches the anchor-5 example of every token earning its place.	5 / 5
Actionability	Concrete, executable guidance throughout: exact paths per subject type, an output template ("File this at `{type}/{slug}.md` because the primary subject is {reason}"), and concrete anti-patterns. Not 5 because key details — the notability gate criteria and the "full filing rules" — are delegated to files not present in the bundle.	4 / 5
Workflow Clarity	Phases 1-4 are clearly sequenced with checkpoints (notability gate in step 4, check-existing implied by the anti-patterns), and the skill is non-mutating so the validation cap does not apply. Not 5 because there is no explicit verify step and the notability gate's criteria live in an external file, leaving checkpoints partially implicit.	4 / 5
Progressive Disclosure	Sections are well organized and references are signaled up front ("> Full filing rules: See `skills/_brain-filing-rules.md`"), but no bundle files exist and both referenced paths (`skills/_brain-filing-rules.md`, `skills/conventions/quality.md`) point outside the skill, so the core filing rules and notability gate cannot be reached or verified. The content split is more than a minor organization gap, fitting anchor 3 better than 4.	3 / 5
	Total	16 / 20 Passed

Description

50%Weight 40%Scale 1-5

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 is concise and states a clear, distinct purpose (filing by primary subject vs. format/source), but it uniformly lands at the midpoint: no "when to use" guidance, sparse natural trigger terms, and a broad "reference for all brain-writing skills" claim that raises conflict risk. Adding an explicit use-when clause and natural trigger phrases would lift most dimensions.

Suggestions

Add an explicit 'Use when...' clause (e.g. 'Use when creating or filing a new brain page, or when unsure which directory a page belongs in') — this currently caps completeness at 3.

Include natural user phrasings and synonyms in the description (e.g. 'where does this go', 'which directory', 'filing rules') so trigger_term_quality reaches full coverage.

Narrow the "Reference for all brain-writing skills" claim to the specific decision this skill makes, reducing overlap risk with sibling brain-writing skills.

Dimension	Reasoning	Score
Specificity	"Decision protocol for filing brain pages by primary subject, not by format or source" names the domain and 1-2 concrete actions, but coverage stops there — cross-linking, notability, and page types are absent from the description. Not 4 because it does not list several specific actions; not 2 because the actions are more than generic.	3 / 5
Completeness	The "what" is clear ("Decision protocol for filing brain pages by primary subject"), but there is no "Use when..." clause or equivalent explicit trigger guidance in the description, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	Relevant keywords like "where new brain files go", "filing", and "brain pages" appear, but common natural variations a user would say (e.g. "where should this note go", "organize pages") are missing. Anchor 3 ("some relevant keywords but missing common variations") is the best fit.	3 / 5
Distinctiveness Conflict Risk	"Reference for all brain-writing skills" explicitly claims applicability to the entire brain-writing skill family, creating overlap risk with sibling skills despite the otherwise distinct filing niche. It falls between anchors 3 and 4 but the blanket scope claim pulls it to 3.	3 / 5
	Total	12 / 20 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: e78f1c3

Reviewed: 5 days 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.