CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugin-variants/gbrain-coding/skills/repo-architecture/SKILL.md

The canonical home for this skill is repo-architecture in garrytan/gbrain

SKILL.md
Quality
Evals
Security

Quality

Content

75%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 tight, highly usable overview: the decision tree, output template, failure handling, and anti-patterns are all directly actionable, and the structure points clearly to deeper material. Remaining gaps are small — a redundant Contract section, an underspecified cross-link step, and references that point outside the skill bundle itself.

Suggestions

Trim or merge the Contract section — its three bullets restate the decision protocol and preview the Anti-Patterns section.

Make the cross-link phase concrete: which related pages or directories to link from, and the link format to use.

Promote "check if a page already exists" from an Anti-Pattern into an explicit phase/validation step in the workflow.

DimensionReasoningScore

Conciseness

The ~45-line body is lean and assumes competence: a concrete decision tree ("About a person → `people/{name-slug}.md`"), an output template, failure handling, and anti-patterns, with no explanation of concepts Claude already knows. Minor trimmable redundancy keeps it at anchor 4 rather than 5: the Contract section ("Every new page is filed by primary subject (not format, not source)") restates the decision protocol and previews the Anti-Patterns section. Not anchor 3, since the redundancy is a single summary section rather than pervasive padding.

4 / 5

Actionability

Concrete, executable guidance throughout: exact directory patterns in the decision tree, a copy-paste output template ("File this at `{type}/{slug}.md` because the primary subject is {reason}."), and specific failure handling ("`get_page` returns `page_not_found` ... confirm the slug with the user before choosing a directory"). Per the scoring notes, absence of code is not penalized in an instruction-only skill. Anchor 4 rather than 5 because "Cross-link. Link from related directories." is underspecified — no indication of which pages to link from or in what format.

4 / 5

Workflow Clarity

Four clearly numbered phases with an explicit checkpoint ("Check notability. See `skills/conventions/quality.md` notability gate") and an error-recovery section covering fallbacks (fall back to `skills/_brain-filing-rules.md`; confirm the slug on `page_not_found`). Anchor 4 rather than 5 because the "check if a page already exists" validation appears only in Anti-Patterns rather than as a workflow step, and the notability gate's criteria are deferred to an external file. The destructive/batch cap does not apply — the skill is advisory (`mutating: false`).

4 / 5

Progressive Disclosure

The body is a genuine overview with clearly signaled, one-level-deep references — "> **Full filing rules:** See `skills/_brain-filing-rules.md`" at the top, plus `skills/conventions/quality.md` and `../conventions/agent-operator-protocol.md` — and well-organized sections (Contract, Phases, Output Format, When it fails, Anti-Patterns). Anchor 4 rather than 5 because no bundle directories exist to verify the referenced files and the references are repo-relative code-formatted paths rather than links within the skill bundle, a minor navigation/organization gap.

4 / 5

Total

16

/

20

Passed

Description

70%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.

A concise, third-person description of a distinct niche with genuinely natural trigger phrases supplied via `triggers` and `when_to_use`. Its main weakness is that the what and when are split across separate frontmatter fields and the description itself names only one concrete action, so it reads as slightly under-specified when the description field alone is surfaced.

Suggestions

Fold the 'Use when the user asks...' trigger phrases into the description field itself so both what and when are present wherever only `description` is read.

Add one or two more concrete actions to the description, e.g. "walks the decision tree to map a subject to a directory like people/ or companies/ and returns the target path", to lift specificity.

Reconsider "Reference for all brain-writing skills" — stating the audience dilutes distinctiveness; the filing niche and triggers already carry the identity.

DimensionReasoningScore

Specificity

"Where new brain files go. Decision protocol for filing brain pages by primary subject, not by format or source." names the domain and the core action, but does not enumerate several concrete operations. This matches anchor 3 (domain plus 1-2 concrete actions, not comprehensive): above anchor 2 because the stated action is specific rather than generic, below anchor 4 because there is no list of multiple specific actions.

3 / 5

Completeness

The 'what' is explicit in the description ("Decision protocol for filing brain pages by primary subject, not by format or source"), and the 'when' is explicit via the frontmatter `when_to_use` ("Use when the user asks: 'where does this go', 'filing rules', 'create new page', 'which directory'.") plus a `triggers` list, so the missing-'Use when' cap does not apply. Not a 5 because the when-guidance lives in separate frontmatter fields rather than the description field itself, so the description alone does not answer when — matching anchor 4 (both present, when could be more integrated).

4 / 5

Trigger Term Quality

The frontmatter triggers — "where does this go", "filing rules", "create new page", "which directory" — are natural phrases a user would actually say, and the description's "Where new brain files go" mirrors "where does this go". Common synonyms are missing (e.g., "where should I put this", "new note", "organize pages"), so anchor 4 (good coverage, a few natural terms missing) fits better than anchor 5.

4 / 5

Distinctiveness Conflict Risk

The niche is clear (brain-page filing) with distinctive trigger phrases, but "Reference for all brain-writing skills" deliberately broadens its scope to serve sibling brain-writing skills, creating minor overlap risk with closely related skills. Anchor 4 (mostly distinct, minor overlap risk) fits; not 5 because of that broadened self-description.

4 / 5

Total

15

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 1 suspicious

Warning

Total

14

/

16

Passed

Repository

garrytan/gbrain

Path

plugin-variants/gbrain-coding/skills/repo-architecture/SKILL.md

Reviewed

Table of Contents

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.