session-sync

Quick-sync session work to specs/*.md and project-tech.json

Quality

42%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./.codex/skills/session-sync/SKILL.md

Quality

Content

77%

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

This is a well-structured, highly actionable skill with clear workflow sequencing and validation checkpoints. Its main weakness is length — the full inline implementation code makes it token-heavy when a more concise approach with external references could achieve the same clarity. The error handling table and usage examples are strong additions.

Suggestions

Consider moving the detailed JavaScript implementation into a separate reference file and keeping only the process overview and key decision points in SKILL.md to improve conciseness.

Remove obvious code comments like '// Show preview' and '// BLOCKS (wait for user response)' that don't add value for Claude.

Dimension	Reasoning	Score
Conciseness	The skill is reasonably efficient but includes some unnecessary verbosity — the full JavaScript implementation blocks are quite long and could be tightened. The process overview ASCII diagram is helpful but the implementation sections repeat information already conveyed there. Some code comments explain obvious things.	2 / 3
Actionability	The skill provides fully concrete, executable JavaScript code for every step, specific CLI usage examples with flags, concrete data structures (techEntry schema), and a clear category detection function. The code is copy-paste ready and leaves little ambiguity about what to do.	3 / 3
Workflow Clarity	The 5-step process is clearly sequenced with an explicit preview/confirmation checkpoint before writing (Step 3), deduplication checks in Step 4, and an error handling table covering failure modes. The feedback loop of preview -> confirm/cancel -> write is well-defined.	3 / 3
Progressive Disclosure	The content is well-structured with clear sections and a process overview before diving into implementation details. However, for a skill this long (~150+ lines of implementation), the detailed JavaScript code could be split into a separate reference file. The related commands section provides good navigation but no bundle files exist to offload content to.	2 / 3
	Total	10 / 12 Passed

Description

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 extremely terse and relies on internal jargon without explaining what the skill actually does or when it should be used. It fails to provide concrete actions, natural trigger terms, or explicit usage guidance, making it very difficult for Claude to correctly select this skill from a pool of available options.

Suggestions

Explain what 'quick-sync session work' means concretely — e.g., 'Saves current session state by writing updated specifications to specs/*.md files and updating project-tech.json with current technology choices.'

Add a 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to save progress, sync specs, update project documentation, or persist session changes.'

Replace jargon like 'quick-sync session work' with plain language describing the actual operations performed (e.g., 'writes', 'updates', 'persists').

Dimension	Reasoning	Score
Specificity	The description uses vague language like 'quick-sync session work' without explaining what concrete actions are performed. It mentions file paths but doesn't describe what is actually done with them.	1 / 3
Completeness	Neither the 'what' nor the 'when' is clearly answered. There is no 'Use when...' clause, and the description doesn't explain what syncing entails or what triggers its use.	1 / 3
Trigger Term Quality	The terms 'quick-sync', 'session work', 'specs/*.md', and 'project-tech.json' are internal jargon and file paths, not natural keywords a user would say when requesting this functionality.	1 / 3
Distinctiveness Conflict Risk	The specific file paths (specs/*.md, project-tech.json) provide some distinctiveness that would reduce conflict with other skills, but the vague 'quick-sync session work' phrase could overlap with other synchronization or session-related skills.	2 / 3
	Total	5 / 12 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: catlog22/Claude-Code-Workflow
Commit: 07491b0

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