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

69%

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

Quality

Content

52%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill serves as a comprehensive conventions reference but suffers significantly from duplication and verbosity. Key sections like the three-layer model and writing style rules appear twice in near-identical form. The actionability is strong with concrete examples, commands, and patterns, but the document would benefit enormously from moving detailed specifications into the referenced files it already points to and keeping only summaries inline.

Suggestions

Remove the duplicated three-layer model table and writing style section; keep one canonical version and reference it, or consolidate into a single occurrence.

Move the detailed backlog vocabulary (status values, legacy migrations, type unions, source unions, ID schemas) into a referenced file like references/backlog-spec.md, keeping only a brief summary inline.

Move the full writing style forbidden-word list and scanning rules into a referenced file, keeping only the top 3-4 most important rules inline with a pointer to the complete list.

Add a validation step to the project initialization workflow (e.g., 'Verify structure: find _devprocess -type d | sort and confirm all expected directories exist').

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~500+ lines, with massive duplication between sections (e.g., the three-layer model table appears twice nearly identically, writing style rules are stated in full twice in sections 4 and the later 'Writing style for every artifact' section). Many details like the full backlog vocabulary, status migration mappings, and exhaustive forbidden-word lists could be in referenced files rather than inlined. Claude doesn't need concepts like what active voice means explained.	2 / 5
Actionability	The skill provides concrete, executable guidance: specific mkdir commands for project initialization, exact file naming patterns with examples, precise table column orders, specific tool commands (e.g., `python3 tools/github-integration/flow.py tag-phase`), and clear ID schemas. Minor gaps exist where some references point to files not provided (e.g., `references/codebase-awareness.md`, `references/directory-structure.md`) without inline fallback.	4 / 5
Workflow Clarity	The Feature Lifecycle section provides a clear 8-step sequence with explicit ordering constraints (e.g., 'Create row FIRST', 'AFTER the row exists'). The Plan Structure and Git Workflow sections are well-sequenced. However, the project initialization workflow lacks validation checkpoints (no step to verify the created structure), and the writing style 'grep before save' is described but not formalized as a validation step with error recovery.	4 / 5
Progressive Disclosure	The skill references several external files (references/codebase-awareness.md, references/directory-structure.md, references/naming-conventions.md, various templates) which is good in principle, but the SKILL.md itself inlines enormous amounts of detail that should live in those referenced files. The three-layer model, backlog vocabulary, writing style rules, and naming conventions are all fully specified inline despite having dedicated reference files. The content that is inlined (~500+ lines) makes this effectively a monolithic document with references that are redundant rather than complementary.	2 / 5
	Total	12 / 20 Passed

Description

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

This is a solid description with excellent trigger term coverage and completeness, explicitly stating both what the skill does and when to use it. Its main weakness is that the 'what' portion could be more specific about concrete actions (e.g., creating directory trees, generating config files) rather than relying on somewhat abstract terms like 'way of working'. Overall, it would perform well in a multi-skill selection scenario.

Suggestions

Replace the vague 'way of working' with more concrete actions such as 'scaffolding directory trees', 'generating configuration files', or 'setting up documentation templates' to improve specificity.

Dimension	Reasoning	Score
Specificity	Names the domain (project structure/conventions) and lists a few concrete areas it covers—'project structure, naming conventions, and way of working'—but 'way of working' is vague and it doesn't enumerate specific actions like creating directories, generating config files, or scaffolding templates.	3 / 5
Completeness	Clearly answers both 'what' (defines project structure, naming conventions, way of working; referenced by other skills for consistency) and 'when' (explicit 'Use this skill when...' clause with concrete trigger phrases, plus the additional context of being relevant when starting a new project).	5 / 5
Trigger Term Quality	Includes a comprehensive set of natural trigger terms: 'project setup', 'project structure', 'conventions', 'init', 'initialize project', 'directory structure', plus the catch-all 'starting a new project'. These are terms users would naturally say.	5 / 5
Distinctiveness Conflict Risk	Fairly distinct with its focus on project structure and conventions, and the mention of being 'referenced by other skills' clarifies its meta/foundational role. Minor overlap risk with skills that handle scaffolding or boilerplate generation, but the trigger terms are specific enough to mostly avoid conflicts.	4 / 5
	Total	17 / 20 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (667 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: salemaziel/digital-innovation-agents
Path: skills/project-conventions/SKILL.md
Commit: 055b016

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