session-sync
Quick-sync session work to specs/*.md and project-tech.json
56
47%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.codex/skills/session-sync/SKILL.mdQuality
Discovery
17%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 overly terse and relies on project-specific jargon without explaining what the skill actually does or when it should be used. It lacks natural trigger terms and explicit 'Use when...' guidance, making it difficult for Claude to reliably select this skill from a pool of options.
Suggestions
Add a 'Use when...' clause that describes the situations triggering this skill, e.g., 'Use when the user wants to save or persist current session progress to specification files.'
Replace jargon like 'quick-sync' with concrete action verbs describing what happens, e.g., 'Writes current session decisions, changes, and technical details to specs/*.md files and updates project-tech.json.'
Include natural trigger terms users might say, such as 'save progress', 'update specs', 'persist session', 'write to spec files', or 'update project config'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names a specific action ('sync session work') and specific targets ('specs/*.md and project-tech.json'), but the description is terse and doesn't elaborate on what 'quick-sync' entails or what concrete operations are performed. | 2 / 3 |
Completeness | The 'what' is vaguely implied (syncing session work to specific files) but poorly explained, and there is no 'when' clause or explicit trigger guidance at all, which per the rubric caps completeness at 2 at best—but the 'what' is also too weak to merit a 2. | 1 / 3 |
Trigger Term Quality | Uses project-specific jargon like 'quick-sync', 'specs/*.md', and 'project-tech.json' that users would not naturally say. There are no common natural language trigger terms a user would use to invoke this skill. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of specific file paths ('specs/*.md', 'project-tech.json') provides some distinctiveness, but 'sync session work' is vague enough that it could overlap with other syncing or documentation skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
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, actionable skill with clear workflow sequencing and good error handling. Its main weakness is that the full implementation is inlined, making it longer than necessary for a SKILL.md overview — the JavaScript implementation could be extracted to a bundle file. The content is concrete and executable throughout, with a solid preview-confirm-write pattern.
Suggestions
Extract the full JavaScript implementation into a bundle script file and reference it from SKILL.md, keeping only the process overview and key decision points inline.
Trim redundant inline comments in the code blocks (e.g., '// BLOCKS (wait for user response)') that describe behavior obvious from the code itself.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary verbosity — the full JavaScript implementation details are quite lengthy for what is essentially a sync script. The inline code could be more concise, and some comments are redundant (e.g., explaining what detectCategory does when the code is self-evident). However, it doesn't explain basic concepts Claude already knows. | 2 / 3 |
Actionability | The skill provides fully concrete, executable JavaScript code with specific commands, file paths, data structures, and clear logic. The usage examples with CLI flags are copy-paste ready, and the implementation covers all steps with real code rather than pseudocode. | 3 / 3 |
Workflow Clarity | The 5-step process is clearly sequenced with explicit validation: Step 3 provides a preview and confirmation gate before writing, Step 4 includes deduplication checks before writing, and the error handling table covers failure modes with resolutions. The feedback loop (preview -> confirm/cancel -> write) is well-defined. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and a process overview before implementation details. However, the full implementation is inline (~150+ lines of code) rather than being split into a referenced script file. The Related Commands section provides good navigation to sibling skills, but the monolithic implementation block could benefit from being extracted. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%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
227244f
- 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.