session-sync
Quick-sync session work to specs/*.md and project-tech.json
41
42%
Does it follow best practices?
Impact
—
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
7%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 provides specific file paths which offer slight distinctiveness, but the lack of concrete actions, natural trigger terms, and explicit usage guidance makes it very difficult for Claude to correctly select this skill from a pool of available options.
Suggestions
Explain what 'quick-sync session work' means in concrete terms — e.g., 'Updates specification markdown files and project-tech.json with current session progress, decisions, and technical changes.'
Add a 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to save progress, update specs, sync session notes, or persist decisions to project documentation.'
Include natural keywords users might say, such as 'save progress', 'update specs', 'sync notes', 'persist changes', 'update project config'.
| 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 | The description fails to clearly answer 'what does this do' (what does syncing session work mean?) and completely lacks any 'when should Claude use it' guidance. There is no 'Use when...' clause or equivalent. | 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. A user would not naturally use these terms to invoke this skill. | 1 / 3 |
Distinctiveness Conflict Risk | The specific file paths (specs/*.md, project-tech.json) provide some distinctiveness and reduce conflict risk with other skills, but the vague 'quick-sync session work' portion could overlap with other synchronization or documentation skills. | 2 / 3 |
Total | 5 / 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, highly actionable skill with clear workflow sequencing and validation checkpoints. Its main weakness is that the full implementation is inlined, making it longer than necessary for a SKILL.md overview — some implementation details could be extracted to supporting files. The code is concrete and executable, and the error handling table is a nice practical touch.
Suggestions
Consider extracting the helper functions (detectCategory, detectSubFeature) and the full Step 4 write logic into a referenced implementation file to keep SKILL.md as a concise overview.
The confirmation UI code in Step 3 is quite detailed — consider condensing it to show the key logic (preview format + confirmation gate) without the full options/labels verbosity.
| 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 helper functions (detectCategory, detectSubFeature) and the confirmation UI code could be more compact. However, it doesn't explain basic concepts Claude already knows. | 2 / 3 |
Actionability | The skill provides fully concrete, executable JavaScript code for every step, specific CLI usage examples with flags, and clear data structures (techEntry schema, guidelineUpdates format). The error handling table adds practical resolution steps. | 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 a clear feedback mechanism. The ASCII flow diagram at the top provides a quick overview of the pipeline. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and a usage summary up top, but the full implementation is inlined in a single file rather than being split into referenced files. For a skill of this length (~150+ lines of code), some of the implementation details could be offloaded. The related commands section at the bottom provides good cross-references. | 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
5ff5e86
- 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.