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 that a user would employ, and the absence of a 'Use when...' clause makes it difficult for Claude to know when to select this skill from a larger set.
Suggestions
Add a 'Use when...' clause specifying triggers, e.g., 'Use when the user wants to save or persist session progress, update specification documents, or refresh project-tech.json.'
Replace jargon like 'quick-sync session work' with concrete actions, e.g., 'Writes current session decisions, design changes, and technical updates to specification markdown files and project-tech.json.'
Include natural language trigger terms users might say, such as 'save progress', 'update specs', 'persist changes', 'sync project files'.
| 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 'sync session work' concretely entails or what operations are performed. | 2 / 3 |
Completeness | The 'what' is vaguely implied (syncing session work to files) but not clearly explained, and there is no 'when' clause or explicit trigger guidance at all. Missing a 'Use when...' clause caps this at 2, and the weak 'what' brings it to 1. | 1 / 3 |
Trigger Term Quality | Uses project-specific jargon ('quick-sync', 'specs/*.md', 'project-tech.json') that a user would not naturally say. There are no common natural language trigger terms like 'save progress', 'update specs', or 'sync changes'. | 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 file-writing 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-crafted skill with strong actionability and clear workflow sequencing including validation checkpoints. The main weakness is that the full implementation is inlined, making it lengthy, and some code comments explain obvious patterns. The error handling table and usage examples are excellent additions that make the skill practical.
Suggestions
Consider moving the detailed implementation code (Steps 1-4) into a separate reference file and keeping only the process overview and key decision points in SKILL.md
Remove explanatory comments like '// BLOCKS (wait for user response)' and '// populated by agent analysis' that describe obvious behavior to Claude
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly detailed and well-structured, but includes some unnecessary verbosity—like the Chinese text in the confirmation prompt, the extensive code comments explaining obvious logic, and the full implementation of helper functions like detectCategory/detectSubFeature that could be more concise. Some sections could be tightened. | 2 / 3 |
Actionability | The skill provides fully concrete, executable JavaScript code for every step, specific CLI usage examples with flags, clear data structures (techEntry schema, guidelineUpdates format), and explicit file paths. The implementation is copy-paste ready with real function calls and logic. | 3 / 3 |
Workflow Clarity | The 5-step process is clearly sequenced with a visual flow diagram, includes a 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 explicit. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and a process overview before diving into implementation details, but the full implementation is inline rather than being split into referenced files. For a skill of this length (~150+ lines of implementation), some of the detailed code could be externalized. The related commands section at the end 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
0f8e801
- 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.