Skip to content

[JEWEL-1342] Move Jewel and YouTrack skills to .agents/skills - #3600

Open
Sebastiano Poggi (rock3r) wants to merge 1 commit into
JetBrains:masterfrom
rock3r:sebp/JEWEL-1342_move-jewel-skills-to-.agents
Open

[JEWEL-1342] Move Jewel and YouTrack skills to .agents/skills#3600
Sebastiano Poggi (rock3r) wants to merge 1 commit into
JetBrains:masterfrom
rock3r:sebp/JEWEL-1342_move-jewel-skills-to-.agents

Conversation

@rock3r

@rock3r Sebastiano Poggi (rock3r) commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

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-youtrackyoutrack-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 in intellij-community and cannot be made to exist from here, since the youtrack skill 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

  • Move jewel-pr-preparer and jewel-release-helper from .claude/skills to .agents/skills, with their scripts intact, and regenerate their .claude/skills stubs.
  • Move the YouTrack CLI skill to .agents/skills/youtrack-community, carrying yt.py, its test suite, references, and evals unchanged, and regenerate its .claude/skills stub.
  • State the Community-only scope in the skill body and description, and direct monorepo users to the youtrack skill.
  • Shorten the three skills' descriptions to single lines. The guide renderer hard-fails above 160 UTF-8 bytes per skill and 6 KiB per edition (.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.
  • Regenerate .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/skills and .claude/skills, which looks like duplication but is the layout this repository already uses. .agents/skills holds the canonical source; .claude/skills holds 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 — and AgentGuidelinesConsistencyTest fails 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.mjs cannot 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 at community/.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.json parses, and no references to the old skill name remain.

@rock3r

Copy link
Copy Markdown
Collaborator Author

Ready to merge

@rock3r
Sebastiano Poggi (rock3r) force-pushed the sebp/JEWEL-1342_move-jewel-skills-to-.agents branch from 2901977 to e1d0343 Compare August 5, 2026 14:23
@rock3r

Copy link
Copy Markdown
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.

@rock3r
Sebastiano Poggi (rock3r) force-pushed the sebp/JEWEL-1342_move-jewel-skills-to-.agents branch from e1d0343 to e4b569a Compare August 6, 2026 06:12
.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.
@rock3r
Sebastiano Poggi (rock3r) force-pushed the sebp/JEWEL-1342_move-jewel-skills-to-.agents branch from e4b569a to 262241e Compare August 6, 2026 09:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants