CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

project-conventions

Defines project structure, naming conventions, and way of working for all projects. Referenced by other skills to ensure consistent directory structures, file names, and documentation standards. Use this skill when the user mentions "project setup", "project structure", "conventions", "init", "initialize project", "directory structure", or similar. Also automatically relevant when starting a new project.

Quality

81%

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

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 content is exceptionally actionable — exact commands, formats, regexes, and ID schemas throughout — and the lifecycle and init workflows are clearly sequenced. Its two real weaknesses are significant internal duplication (writing-style rules and the three-layer model each appear twice) and an underused references/ bundle where half the files are never linked from the body.

Suggestions

Collapse the duplicated '### 4. Writing style (canonical home)' and '## Writing style for every artifact' sections into one canonical section (the body itself declares 'Phase skills do not restate them; they link back'), and merge the duplicated three-layer model tables in section 7 and the 'Three-layer documentation model' section.

Add one line per orphaned bundle file (e.g., under Git Workflow: 'Branch protection rules: see references/branch-protection.md'; similar pointers for graph-invariants.md and team-workflow.md) so the full bundle is discoverable from SKILL.md.

Add an explicit remediation step for the cap and consistency checks (e.g., 'if wc -l exceeds the cap, split the artifact or add the Reasoned exception block, then re-run the check') to close the validate -> fix -> retry loop the wc -l and /consistency-check checkpoints imply.

DimensionReasoningScore

Conciseness

The body is 655 lines with real duplication: the writing-style rules appear twice in near-verbatim form ('### 4. Writing style (canonical home)' with the full AI-vocabulary list, then again under '## Writing style for every artifact' repeating the same em-dash, vocabulary, filler, and parallelism rules), and the three-layer model table appears twice ('### 7. Three-layer model boundaries' and '## Three-layer documentation model' with the same Wayfinder/Rule sets/Backlog/Detail artifacts rows and much of the same rationale). This matches anchor 3 (mostly efficient but includes some unnecessary explanation or could be tightened). Not 4 because whole duplicated sections are more than minor trimmable instances; not 2 because the bulk is genuinely novel project-specific binding rules (caps, ID schemas, status vocabulary), not explanations of concepts Claude already knows.

3 / 5

Actionability

Guidance is fully concrete and copy-paste ready: the exact scaffold command 'mkdir -p _devprocess/{analysis/sources,requirements/{epics,features,fixes,improvements,handoff},architecture,rules,implementation/plans,context}', the binding column order '| ID | Type | Title | Status | Phase | Prio | Refs | Source | Commit | Claim | Last change | Notes |', the anchored regex '^## Activation Path\s*$', the tag command 'python3 tools/github-integration/flow.py tag-phase --item <ID> --phase <phase>', and ID patterns with worked examples like 'IMP-04-02-01'. This matches anchor 5 for an instruction-only skill (fully executable guidance; specific examples cover the common cases). Not 4 because there are no missing key details in the main flows — every convention comes with a format, example, or tool pointer.

5 / 5

Workflow Clarity

The '## Feature Lifecycle' section gives an explicit 8-step sequence (BACKLOG ROW -> CLAIM -> FEATURE-SPEC -> PLAN -> IMPLEMENTATION -> SPEC UPDATE -> WAYFINDER UPDATE -> BACKLOG UPDATE) with ordering constraints like 'Status-changing actions update the backlog row BEFORE the artifact body', and '## Initializing a Project' is an executable runbook. Validation checkpoints exist but are declarative rather than procedural: 'Skills measure with `wc -l` against the cap before handoff' and '/consistency-check flags the artifact as over-cap'. This matches anchor 4 (clear sequence with most checkpoints present; minor validation gaps). Not 5 because there is no explicit validate -> fix -> retry loop telling the agent what to do when the wc -l check or consistency-check fails (the fix path lives only implicitly in other skills); not 3 because checkpoints are stated for the risky steps, not absent.

4 / 5

Progressive Disclosure

Three of the six bundle files are well-signaled at one level deep ('Read `references/codebase-awareness.md` for the complete rules', 'Read `references/directory-structure.md` for the full reference', 'Read `references/naming-conventions.md` for the full reference'), but the other three — `references/branch-protection.md`, `references/graph-invariants.md`, `references/team-workflow.md` — are never referenced anywhere in the body, leaving roughly half the bundle undiscoverable; meanwhile the duplicated canonical-specs and writing-style sections are exactly the 'content that should be separate is inline' pattern. This matches anchor 3 (some structure but could be better organized; references present but not clearly signaled). Not 4 because unreferenced bundle files plus a fully duplicated spec section are more than minor organization gaps; not 2 because the three signaled references are clear, one level deep, and the body has strong section structure.

3 / 5

Total

15

/

20

Passed

Description

86%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 strong: third-person voice, explicit 'Use this skill when' trigger clause with natural user phrases, and a clear statement of what the skill governs. Its main weakness is that 'what' stays at the level of governed concerns (structure, naming, way of working) rather than naming the concrete artifacts and setup actions the body actually delivers.

Suggestions

Enumerate 2-3 concrete capabilities in the 'what' clause (e.g., 'scaffolds the _devprocess directory tree, defines artifact naming (EPIC/FEAT/ADR/PLAN/FIX IDs), and seeds BACKLOG.md and rules files') to lift specificity from naming the domain to naming actions.

Narrow the 'init' / 'initialize project' triggers with a qualifier (e.g., 'initialize project structure for the V-Model workflow') to reduce overlap risk with generic project-init or CLAUDE.md-setup skills.

DimensionReasoningScore

Specificity

The description names the domain and its outputs via 'Defines project structure, naming conventions, and way of working for all projects' and 'ensure consistent directory structures, file names, and documentation standards', which are 2-3 concrete functions. This matches anchor 3 (names domain and 1-2 concrete actions, but not comprehensive): the actions are what the skill governs rather than an enumeration of what it concretely produces (e.g., creating the _devprocess tree, seeding BACKLOG.md, validating artifacts). Not 4 because it does not list several specific actions with only minor gaps; not 2 because it goes beyond naming the domain with generic language.

3 / 5

Completeness

It explicitly answers both questions: 'what' via 'Defines project structure, naming conventions, and way of working for all projects. Referenced by other skills to ensure consistent directory structures, file names, and documentation standards' and 'when' via 'Use this skill when the user mentions ...'. This is the anchor 5 pattern (clearly and explicitly answers both what AND when with concrete trigger phrases), mirroring the good example 'Extract text and tables from PDF files ... Use when working with PDF files'. Not 4 because the 'when' is already fully explicit with concrete trigger phrases rather than merely present.

5 / 5

Trigger Term Quality

The 'when' clause supplies natural phrases a user would actually say: '"project setup", "project structure", "conventions", "init", "initialize project", "directory structure", or similar', plus 'Also automatically relevant when starting a new project'. This matches anchor 5 (comprehensive coverage of natural terms including synonyms and variations) — it covers setup/structure/conventions/init variants and an implicit-trigger case. Not 4 because no obviously common synonym is missing; the 'or similar' catch-all plus the automatic-relevance clause round out coverage.

5 / 5

Distinctiveness Conflict Risk

The niche (cross-project structural and naming conventions for a V-Model documentation workflow) is distinct, with triggers like 'directory structure' and 'naming conventions' that few other skills would claim. It matches anchor 4 (mostly distinct; minor overlap risk with closely related skills): 'init' / 'initialize project' overlaps generic project-init and CLAUDE.md-initialization skills, and 'conventions' is broad. Not 5 because those init/convention triggers carry some conflict risk; not 3 because the core triggers are specific to this skill's documented domain.

4 / 5

Total

17

/

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

skill_md_line_count

SKILL.md is long (667 lines); consider splitting into references/ and linking

Warning

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

14

/

16

Passed

Repository

salemaziel/digital-innovation-agents

Path

skills/project-conventions/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.