schema-author

Evolve your brain's schema pack. Add page types, propose new ones from corpus scans, backfill page.type on existing pages, audit pack health. Triggers when an agent notices untyped pages, custom domains needing typed entities (researcher, contract, deposition), or wants to see what types the pack declares.

Quality

80%

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

Quality

Content

77%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 highly actionable with an exemplary validated workflow (dry-run gates, lint, verify, failure recovery). Its weaknesses are redundancy between the Outputs and Contract sections and time-sensitive version detail inline, plus inlined reference material and unresolvable convention paths given the empty bundle.

Suggestions

Merge the Outputs and Contract sections into one, keeping the single fuller treatment of pack file, audit row, backfill, trust, and atomicity to remove the duplication.

Move the JSON output examples and the error-code list into a references/ file (e.g. references/outputs.md) and link to it one level deep, which also gives the conventions and sibling-skill paths a real bundle to resolve against.

Relocate version-specific history (v0.40.6.0 wiring, cross-process invalidation gap) into an 'old patterns' / 'version notes' section or the referenced conventions doc, and use one canonical path for schema-evolution.md.

Dimension	Reasoning	Score
Conciseness	The body is command-dense and assumes competence, but the Outputs and Contract sections duplicate each other (both enumerate the pack file, audit row, and backfilled pages.type), and version-history asides ("added in v0.40.6.0 — pre-v0.40.6 brains silently ignored custom expert-routed types") are time-sensitive content placed outside any old-patterns section.	3 / 5
Actionability	Every phase gives copy-paste-ready commands with concrete flags (gbrain schema add-type researcher --primitive entity --prefix people/researchers/ --extractable --expert, lint --with-db, sync --apply) plus a worked batched-mutation JSONL example and a git commit sequence, fully covering the common cases.	5 / 5
Workflow Clarity	Seven clearly sequenced phases embed explicit validation checkpoints for the batch/destructive operations: lint --with-db before write, sync dry-run with would_apply counts and sample slugs before --apply, post-apply verification via stats and whoknows, and a Failure modes section with recovery steps per error code.	5 / 5
Progressive Disclosure	Section structure is good and conventions are referenced one level deep, but no bundle files exist, the referenced paths (../conventions/schema-evolution.md, also inconsistently cited as skills/conventions/schema-evolution.md) cannot be verified, and ~40 lines of JSON output/error-code reference material are inlined in the SKILL.md rather than split into a references file.	3 / 5
	Total	16 / 20 Passed

Description

83%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 strong description with an explicit trigger clause and several concrete, domain-specific actions. Its main gaps are partial coverage of the skill's mutation primitives and trigger phrasing that leans on the separate triggers list rather than natural synonyms embedded in the description itself.

Suggestions

Fold 2-3 of the most natural user phrasings from the triggers list (e.g. "add a type to my schema", "extend the schema pack") into the description's trigger sentence so natural keywords are self-contained.

Mention the fork-and-mutate flow and link/alias primitives briefly so the 'what' covers the skill's full authoring surface, not just add/backfill/audit.

Drop or reframe "wants to see what types the pack declares" to avoid overlap with the read-only lookup job this skill's own Non-goals section routes elsewhere.

Dimension	Reasoning	Score
Specificity	The description lists four concrete actions ("Add page types, propose new ones from corpus scans, backfill page.type on existing pages, audit pack health"), matching the several-specific-actions anchor, but the skill's full mutation surface (fork, remove, aliases, prefixes, link verbs) is only partially covered, so it falls short of comprehensive.	4 / 5
Completeness	It explicitly answers both what ("Evolve your brain's schema pack. Add page types, propose new ones... backfill page.type... audit pack health") and when ("Triggers when an agent notices untyped pages..."), with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Natural phrases like "untyped pages", "custom domains needing typed entities", and "see what types the pack declares" give good keyword coverage, but some common user phrasings (e.g. "add a type to my schema", "extend the schema") appear only in the separate triggers list, not the description itself.	4 / 5
Distinctiveness Conflict Risk	The schema-pack authoring niche is clear and mostly distinct, but "wants to see what types the pack declares" overlaps a read-only lookup job the body explicitly routes elsewhere, leaving minor conflict risk with sibling skills like brain-taxonomist.	4 / 5
	Total	17 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 suspicious	Warning

	Total	14 / 16 Passed

Repository: garrytan/gbrain
Path: skills/schema-author/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.