structural-pre-flight

Authoritative pre-implementation discipline gate that fires when a new `.mjs` file is about to be authored. Stage 0 mechanical trigger; Stage 1 fast-path (sibling-file-lift pattern match) for matched patterns OR full Pre-Flight (ArchitectureOverview.md + ADR consultation + chief-architect framing) for novel directory choices. Closes the 0th-level discipline gap empirically demonstrated by `ai/daemons/wake/daemon.mjs` (originally misplaced in `ai/scripts/` as `bridge-daemon.mjs`) and `orchestrator-daemon.mjs` (PR #11008 same-class miss). Triggers: Use this skill before authoring or relocating any new `.mjs` file. Fires from `ticket-create` Stage 3 (Substrate), `ticket-intake` validation, `epic-review` Stage 3, and any direct authoring path. Sibling pattern match → 30-second fast-path; novel directory choice → full structural pre-flight before the file is written.

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/structural-pre-flight/SKILL.md

Quality

Content

80%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 SKILL.md body is an exemplary lean overview: concise, correctly delegating detail to a single one-level-deep reference that exists in the bundle. Its only real weakness is workflow clarity — the two-stage sequence is named but the validation checkpoints live entirely in the reference, so the body alone gives only a rough shape.

Dimension	Reasoning	Score
Conciseness	The body is two lean paragraphs that assume Claude's competence and defer all detail to the reference; every token earns its place with no over-explanation of concepts Claude already knows.	5 / 5
Actionability	Gives one fully executable instruction — 'use the view_file tool to read and strictly adhere to .agents/skills/structural-pre-flight/references/structural-pre-flight-workflow.md' (specific tool + concrete path) — but the substantive authoring guidance lives one hop away in the reference rather than inline, leaving a minor gap.	4 / 5
Workflow Clarity	The body names the two stages ('30-second sibling-pattern fast-path AND a full Pre-Flight for novel directory choices') and the mandatory reasoning-statement, so a rough sequence is present, but validation checkpoints and the step-by-step sequencing are deferred entirely to the reference rather than surfaced in the body.	3 / 5
Progressive Disclosure	The body is a clean overview pointing to exactly one well-signaled, one-level-deep reference (structural-pre-flight-workflow.md, present in ./references/); content is appropriately split and navigation is unambiguous.	5 / 5
	Total	17 / 20 Passed

Description

80%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 complete and distinct, explicitly covering both what the skill does and when to fire it with a concrete trigger clause. Its weakness is trigger-term quality: the phrasing is dominated by project-internal jargon and historical anchors rather than the natural terms a user would say.

Suggestions

Lead with the natural trigger phrase ('Use before authoring or relocating any new .mjs file') and push the Stage 0/Stage 1 mechanics lower, so a user scanning skill descriptions sees the everyday trigger first.

Replace or gloss internal terms ('sibling-file-lift', '0th-level discipline gap', 'chief-architect framing') with plain-language equivalents a user would actually say.

Move the empirical anchors (the daemon.mjs / PR #11008 misplacement history) into the reference body; they justify the skill but pad the description with non-capability detail.

Dimension	Reasoning	Score
Specificity	Names several concrete mechanisms — 'sibling-file-lift pattern match', 'ArchitectureOverview.md + ADR consultation + chief-architect framing', 'map-maintenance' — but the capability list is diluted by historical narrative ('originally misplaced in ai/scripts/ as bridge-daemon.mjs', 'PR #11008 same-class miss') that is not itself a capability, leaving minor gaps.	4 / 5
Completeness	Explicitly answers both: what ('Authoritative pre-implementation discipline gate that fires when a new .mjs file is about to be authored' plus the Stage 0/Stage 1 mechanism) and when ('Triggers: Use this skill before authoring or relocating any new .mjs file'), with concrete trigger phrases, so the missing-trigger cap does not apply.	5 / 5
Trigger Term Quality	Natural user-facing triggers are limited to 'new .mjs file' and 'authoring or relocating any new .mjs file'; the rest is dense internal jargon ('Stage 0 mechanical trigger', 'sibling-file-lift', '0th-level discipline gap', 'ticket-create Stage 3', 'epic-review Stage 3') that a user would not naturally say, missing common synonyms.	3 / 5
Distinctiveness Conflict Risk	Occupies a narrow, well-defined niche — directory-choice discipline for .mjs files before authoring — with distinct triggers ('before authoring or relocating any new .mjs file') and minimal overlap with sibling skills that fire later in the pipeline.	5 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: neomjs/neo
Path: .agents/skills/structural-pre-flight/SKILL.md
Commit: 210c03c

Reviewed: 3 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.