working-with-jj
Expert guidance for using JJ (Jujutsu) version control system. Use when working with JJ, whatever the subject. Operations, revsets, templates, debugging change evolution, etc. Covers JJ commands, template system, evolog, operations log, and interoperability with git remotes.
90
88%
Does it follow best practices?
Impact
90%
1.26xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
89%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 is a solid skill description that clearly identifies its niche (JJ/Jujutsu VCS) and provides good trigger term coverage with domain-specific terminology. The main weakness is that capabilities are described more as topic areas than concrete actions—it could benefit from more action-oriented language. The 'Use when' clause is present and broad, which is appropriate for a comprehensive JJ skill.
Suggestions
Replace 'Expert guidance for using' with specific action verbs, e.g., 'Writes revset expressions, debugs change evolution, configures git remote interop, and navigates operations/evolog for the JJ (Jujutsu) version control system.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (JJ/Jujutsu version control) and lists several areas like commands, template system, evolog, operations log, and git remote interoperability, but these are more topic areas than concrete actions. It says 'expert guidance' rather than specific verbs like 'debug change evolution conflicts' or 'write revset expressions'. | 2 / 3 |
Completeness | Clearly answers both 'what' (guidance for JJ version control covering commands, templates, evolog, operations log, git interop) and 'when' ('Use when working with JJ, whatever the subject') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'JJ', 'Jujutsu', 'revsets', 'templates', 'evolog', 'operations log', 'git remotes', 'change evolution'. These cover the terms a user working with JJ would naturally use in their queries. | 3 / 3 |
Distinctiveness Conflict Risk | JJ/Jujutsu is a very specific version control system with distinct terminology (revsets, evolog, change evolution). This is unlikely to conflict with generic git skills or other VCS skills due to the highly specific trigger terms. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
87%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality skill file that efficiently covers JJ version control with concrete, actionable commands and excellent progressive disclosure. Its main weakness is the lack of explicit multi-step workflows with validation checkpoints, particularly around risky operations like rebasing or batch description transforms where the checkpoint script could be integrated into a clear workflow. The common pitfalls section is a standout feature that addresses real-world mistakes with clear examples.
Suggestions
Add an explicit workflow for risky operations (e.g., rebase) that integrates jj-checkpoint and jj op restore into a validate-fix-retry loop, such as: 1. Checkpoint, 2. Perform operation, 3. Verify with jj log, 4. If wrong: jj op restore
Consider adding a brief workflow example for the batch-desc script showing checkpoint → batch transform → verify → rollback if needed, since batch operations on descriptions are destructive
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient throughout. It assumes Claude's competence with version control concepts, avoids explaining what VCS is or how Git works, and every section delivers actionable information without padding. The core principles section is appropriately terse. | 3 / 3 |
Actionability | Nearly every section provides concrete, copy-paste-ready commands with clear syntax. The essential commands, revset reference, common pitfalls with ✅/❌ examples, and recovery commands are all directly executable. The pitfalls section is especially well-done with concrete before/after examples. | 3 / 3 |
Workflow Clarity | While individual commands are clear, there's no explicit multi-step workflow with validation checkpoints. The recovery section mentions `jj op log` then `jj op restore` but lacks a feedback loop. The `jj-checkpoint` script is mentioned but not integrated into a workflow showing when to use it before risky operations. For a tool where operations can be destructive (rebase, restore), explicit validation steps would strengthen this. | 2 / 3 |
Progressive Disclosure | Excellent structure with a clear overview in the main file and well-signaled one-level-deep references to `references/revsets.md`, `references/command-syntax.md`, `references/batch-operations.md`, and `scripts/`. The self-documenting `jj help` references are a smart addition. Content is appropriately split between the overview and reference files. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
90%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
- YPares/agent-skills
- Commit
aed1afb
- 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.