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

68%

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 ./skills/repo-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

The body is a tight, actionable instruction skill: an exhaustive decision tree with exact path templates, a concrete output format, and unusually good failure-mode handling. Its one structural weakness is that key supplemental content (full filing rules, notability gate, operator protocol) lives in files outside the skill bundle, so a standalone reader cannot follow the references.

Suggestions

Ship the referenced files inside the skill's references/ directory (or inline the notability gate criteria) so phases 4 and the failure fallbacks are self-contained.

Make the "Cross-link" phase concrete — specify which related 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 step, since the anti-patterns section calls it out but the workflow never instructs it.

DimensionReasoningScore

Conciseness

The body is lean — decision tree, output template, failure handling, and anti-patterns all earn their tokens, with no explanations of concepts Claude already knows. The "Contract" section mildly duplicates the description and the Phases/Anti-Patterns content, which is trimmable, keeping it just below a 5.

4 / 5

Actionability

Highly concrete for an instruction-only skill: exact path templates (e.g., "people/{name-slug}.md", "media/{type}/{slug}.md"), a copy-paste output sentence, and specific error codes ("page_not_found") with recovery actions. The "Cross-link. Link from related directories." step is vague about method and targets, a minor gap that prevents a 5.

4 / 5

Workflow Clarity

A clear four-phase sequence with an explicit validation gate (step 4 notability check) and a "When it fails" section providing concrete error-recovery feedback loops. The "check if a page already exists" validation is only stated as an anti-pattern rather than an explicit phase step, a minor gap that prevents a 5.

4 / 5

Progressive Disclosure

Sections are well organized and references are clearly signaled (blockquote pointer, inline step references, failure-section link), with the core decision tree properly inline. However, the referenced files ("skills/_brain-filing-rules.md", "skills/conventions/quality.md", "../conventions/agent-operator-protocol.md") are not present in the skill bundle — no references/ directory exists — so the navigation dangles and the notability gate depends entirely on an unreachable external file.

3 / 5

Total

15

/

20

Passed

Description

53%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 identifies a clear, distinct niche, with a reasonably concrete statement of what the skill does. Its main weakness is the missing "when to use" guidance and limited natural trigger vocabulary within the description text itself, leaving a user to rely on the separate triggers field.

Suggestions

Add an explicit "Use when..." clause to the description, e.g., "Use when creating a new brain page and deciding which directory it belongs in."

Name the concrete actions the protocol performs (decides target directory, generates the slug, flags misfiled pages) to raise specificity.

Fold one or two natural user phrases ("which directory", "where does this page go") into the description so trigger coverage does not depend solely on the triggers field.

DimensionReasoningScore

Specificity

Names the domain ("brain pages", "filing") and one concrete function ("Decision protocol for filing brain pages by primary subject, not by format or source"), matching the 1-2 concrete actions anchor. It does not list several specific actions (e.g., deciding directories or slugs), so it is not a 4.

3 / 5

Completeness

The "what" is clear (a decision protocol and reference for filing brain pages), but the description contains no "Use when..." clause or equivalent trigger guidance, capping completeness at 3 per the rubric guideline. The frontmatter triggers field mitigates this, but the description field itself leaves "when" unstated.

3 / 5

Trigger Term Quality

Includes the natural phrase "Where new brain files go" plus domain terms ("filing", "primary subject"), but the description alone misses common variations like "which directory", "where does this go", or "organize". The separate frontmatter triggers field supplies natural phrases, but the description text itself has only partial keyword coverage.

3 / 5

Distinctiveness Conflict Risk

The niche is distinct — filing/location decisions for a brain knowledge base — with low conflict risk against unrelated skills. Minor overlap risk remains because "Reference for all brain-writing skills" invites triggering alongside other brain-writing skills.

4 / 5

Total

13

/

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

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.