[JEWEL-1342] Move Jewel and YouTrack skills to .agents/skills - #3600
Open
Sebastiano Poggi (rock3r) wants to merge 1 commit into
Open
[JEWEL-1342] Move Jewel and YouTrack skills to .agents/skills#3600Sebastiano Poggi (rock3r) wants to merge 1 commit into
Sebastiano Poggi (rock3r) wants to merge 1 commit into
Conversation
Sebastiano Poggi (rock3r)
force-pushed
the
sebp/JEWEL-1342_move-jewel-skills-to-.agents
branch
from
August 5, 2026 11:22
274f511 to
2901977
Compare
Nebojsa Vuksic (nebojsa-vuksic)
approved these changes
Aug 5, 2026
Collaborator
Author
|
Ready to merge |
Daniel Bertoldi (DanielSouzaBertoldi)
approved these changes
Aug 5, 2026
Wellington Costa (wellingtoncosta)
approved these changes
Aug 5, 2026
Sebastiano Poggi (rock3r)
force-pushed
the
sebp/JEWEL-1342_move-jewel-skills-to-.agents
branch
from
August 5, 2026 14:23
2901977 to
e1d0343
Compare
Collaborator
Author
|
FYI — had to manually run the render script again and re-duplicate the skills from .agents into .claude, as that is the process. Changed lines grew from +24 -20 to a lot more because of that, but it's only a mechanical copy. No other changes. |
Sebastiano Poggi (rock3r)
force-pushed
the
sebp/JEWEL-1342_move-jewel-skills-to-.agents
branch
from
August 6, 2026 06:12
e1d0343 to
e4b569a
Compare
.agents/skills is the harness-neutral canonical source; .claude/skills holds generated stubs. jewel-pr-preparer, jewel-release-helper and the YouTrack CLI skill were authored in .claude/skills, so they were only ever visible to one harness. Move all three to the canonical tree, the YouTrack one with its scripts, references and evals intact. The YouTrack skill is renamed managing-youtrack -> youtrack-community, and its Community-only scope is now stated in the skill itself rather than left to be inferred. That rename exists because IJAI-345 broke this flow for IJC. It replaced a working, self-contained Community skill with a stub pointing at .agents/skills/youtrack/scripts/youtrack.ts — a path that does not exist in intellij-community and cannot be made to exist from here, because the youtrack skill is monorepo-only. In the monorepo the pointer resolves and the damage is invisible; in a standalone Community checkout it resolves to nothing. The result was a skill whose entire content was an instruction to go use something the reader demonstrably does not have. Every YouTrack capability this repository shipped was removed in exchange for a dangling reference, and the hole stayed open until JEWEL-1367 refilled it. Community is not a staging area for monorepo refactors. A change that is correct only at the ultimate root must not be committed to a file this repository ships on its own; the standalone checkout is the product here, not a degraded view of the monorepo. Renaming to youtrack-community makes the boundary explicit so the next such consolidation cannot quietly hollow this one out again: the name says which checkout it serves, and the skill body says in its first paragraph that monorepo users must use the youtrack skill instead. Descriptions are shortened to single lines. The renderer requires one line of at most 160 bytes per skill and 6 KiB per edition, because descriptions are always loaded into agent context. The three moved skills used folded scalars well past that (414, 347 and 416 bytes); the full set now measures 2885 bytes with the longest at 145. render-guides.mjs could not run in a standalone Community checkout at all. It derived the repository root as two levels above itself, which only holds in the ultimate layout where it sits at community/.ai; here that escaped the checkout entirely and looked for a community/ directory that does not exist, so every invocation failed on ENOENT before rendering anything. I provided a patch to Develar to fix the render script to work in Community, too. Two further things only surface in that layout. guide.md pulls in partials that exist solely as ultimate overrides, so they now resolve to empty here instead of throwing; rendered AGENTS.md is byte-identical either way. And the skill stub passes prune and overwrite their target directories, which in this layout are the same directories they read from, so they are skipped rather than allowed to rewrite their own sources. Guide outputs render; the stub passes remain an ultimate-only concern. Guides are unchanged by this commit. The skill index is regenerated from the patched render script, and lists all 33 skills. The CLI's 124 unit tests pass from the new location.
Sebastiano Poggi (rock3r)
force-pushed
the
sebp/JEWEL-1342_move-jewel-skills-to-.agents
branch
from
August 6, 2026 09:27
e4b569a to
262241e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three agent skills —
jewel-pr-preparer,jewel-release-helper, and the YouTrack CLI — were authored in.claude/skills, which holds generated stubs rather than canonical sources. That made them visible to a single harness only. This moves all three to.agents/skills, the harness-neutral canonical tree.The YouTrack skill is also renamed
managing-youtrack→youtrack-community, because its Community-only scope was previously left to be inferred. IJAI-345 had replaced a working, self-contained Community skill with a stub pointing at.agents/skills/youtrack/scripts/youtrack.ts— a path that does not exist inintellij-communityand cannot be made to exist from here, since theyoutrackskill is monorepo-only. In the monorepo that pointer resolves and the breakage is invisible; in a standalone Community checkout it resolves to nothing, leaving a skill whose entire content was an instruction to use something the reader demonstrably does not have. JEWEL-1367 refilled the hole; this change makes the boundary explicit in the name and in the skill's first paragraph, so the next consolidation cannot quietly hollow it out again.Changes
jewel-pr-preparerandjewel-release-helperfrom.claude/skillsto.agents/skills, with their scripts intact, and regenerate their.claude/skillsstubs..agents/skills/youtrack-community, carryingyt.py, its test suite, references, and evals unchanged, and regenerate its.claude/skillsstub.youtrackskill..ai/render-guides.mjs:310-311); these used folded scalars of 414, 347 and 416 bytes. The full set now measures 2885 bytes, longest 145..agents/skills/INDEX.md, which now lists all 34 skills.Why each skill appears twice in the diff
The diff adds each skill under both
.agents/skillsand.claude/skills, which looks like duplication but is the layout this repository already uses..agents/skillsholds the canonical source;.claude/skillsholds a generated stub carrying the<!-- Generated by community/.ai/render-guides.mjs -->marker, plus a copy of the skill's bundled assets so that harness-specific skill-directory variables resolve to a directory containing the scripts. Every existing skill is checked in that way —kotlin-ui-dsl, added in IJPL-252121, is the most recent example — andAgentGuidelinesConsistencyTestfails the build when a canonical source has no committed stub. The stubs here are generated by the renderer, not hand-written; the counts line up at 34 sources, 34 stubs and 34 index rows, with no orphans in either direction.Various notes
Worth flagging that the 160-byte per-skill limit is an arbitrary local constant, not a platform requirement — the agentskills.io spec allows up to 1024 characters. Those two are not directly comparable: the renderer counts UTF-8 bytes, the spec counts characters, and what actually consumes context is tokens. A non-ASCII character can cost several bytes while still being one character, so a byte budget silently penalises em dashes, accented names and non-Latin scripts more than plain ASCII, and none of the three units maps cleanly onto the cost the budget is presumably trying to control. Compressing descriptions this far also risks degrading skill recall, since the description is the only signal an agent has when deciding whether a skill applies. These are shortened to satisfy the renderer, not because the limit is justified; it would be worth backing that constant with actual retrieval evals, and measuring in tokens if context is the real constraint.
Guide outputs are unchanged by this PR.
render-guides.mjscannot currently run in a standalone Community checkout — it derives the repository root two levels above itself, which only holds in the ultimate layout where it sits atcommunity/.ai— but that fix is out of scope here and has been handed to Vladimir Krivosheev (@develar) as a separate patch.Verification
The YouTrack CLI's 124 unit tests pass from the new location,
evals.jsonparses, and no references to the old skill name remain.