cc-skill-project-guidelines-example

Project Guidelines Skill (Example)

Quality

21%

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/cc-skill-project-guidelines-example/SKILL.md

Quality

Content

42%Scale 1-3

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

This skill is a comprehensive project template but suffers from severe verbosity — it inlines extensive boilerplate code patterns that Claude already knows how to produce (generic API responses, fetch wrappers, custom hooks, basic test fixtures). The actionability is strong with executable examples, but the lack of progressive disclosure means everything is crammed into one large file. The deployment workflow would benefit from explicit validation/recovery steps.

Suggestions

Split code patterns, testing examples, and deployment details into separate referenced files (e.g., PATTERNS.md, TESTING.md, DEPLOYMENT.md) and keep SKILL.md as a concise overview with navigation links.

Remove standard boilerplate code that Claude can generate (generic API response classes, basic fetch wrappers, standard React hooks) and focus only on project-specific conventions that deviate from defaults.

Add explicit validation and error recovery steps to the deployment workflow (e.g., 'If gcloud deploy fails: check logs with `gcloud run logs read`, fix issues, redeploy').

Remove the 'When to Use' meta-explanation about what project skills contain — this is self-evident and wastes tokens.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~250+ lines. It explains basic concepts Claude already knows (what App Router is, how fetch works, generic API response patterns). The architecture diagram, while nice, adds significant token cost. Much of this content (full code examples for standard patterns like custom hooks, API wrappers, test fixtures) is boilerplate Claude can generate on its own. The 'When to Use' section explains what project skills are, which is unnecessary meta-commentary.	1 / 3
Actionability	The skill provides fully executable, copy-paste ready code examples across Python, TypeScript, and bash. Commands for testing, deployment, and environment setup are concrete and specific. The code patterns are complete and runnable, not pseudocode.	3 / 3
Workflow Clarity	The deployment workflow has a checklist and commands, but lacks explicit validation checkpoints and feedback loops. There's no 'if deployment fails, do X' recovery step. The testing section lists commands but doesn't integrate them into a clear development workflow sequence (e.g., write test → run test → implement → verify).	2 / 3
Progressive Disclosure	This is a monolithic wall of content with no bundle files to offload detail into. The code patterns, testing examples, and deployment details should be split into separate referenced files. The 'Related Skills' section references files that don't exist in the bundle. All content is inlined in one massive file with no actual progressive disclosure structure.	1 / 3
	Total	7 / 12 Passed

Description

0%Scale 1-3

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 description is essentially a placeholder label with no substantive content. It fails on every dimension: it provides no concrete actions, no trigger terms, no 'when to use' guidance, and no distinguishing characteristics. It would be unusable for skill selection in a multi-skill environment.

Suggestions

Replace the placeholder with a concrete description of what the skill does, e.g., 'Enforces project-specific coding standards, naming conventions, and directory structure rules when writing or reviewing code.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about project conventions, coding standards, file organization, or naming patterns.'

Include specific, distinctive keywords that differentiate this from other skills, such as 'coding standards', 'naming conventions', 'project structure', 'style guide', or 'linting rules'.

Dimension	Reasoning	Score
Specificity	The description 'Project Guidelines Skill (Example)' provides no concrete actions whatsoever. It merely names a vague domain ('Project Guidelines') with no indication of what the skill actually does.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. There is no 'Use when...' clause or any equivalent guidance for skill selection.	1 / 3
Trigger Term Quality	There are no natural keywords a user would say. 'Project Guidelines' is generic and '(Example)' suggests this is a placeholder rather than a real description. No actionable trigger terms are present.	1 / 3
Distinctiveness Conflict Risk	'Project Guidelines' is extremely generic and could conflict with any skill related to projects, guidelines, standards, conventions, or documentation. There is nothing distinctive about this description.	1 / 3
	Total	4 / 12 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: popey/claude-code-skills
Path: skills/cc-skill-project-guidelines-example/SKILL.md
Commit: a5a6601

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.