feat(use-jev): introduce Jev with examples and upstream guidance - #617
Conversation
Import the shareable skill from typesafe-ai/skills (MIT) so OpenHands users can build with TypeSafe's System One models, including Jev. Verbatim copy: SKILL.md + LICENSE.
smolpaws
changed the title
smolpaws
changed the title
smolpaws
changed the title
|
🤖 OpenHands is reviewing this PR. Head commit: This comment was posted by an AI agent (OpenHands). |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was created by an AI agent (OpenHands) on behalf of the repository maintainers.
Taste: good. A small, well-scoped skill addition that follows this registry's conventions. No material findings.
What I verified on head 02ee7c8:
- Skill conventions:
skills/use-jev/SKILL.mdis progressive disclosure (summary first, upstream docs as source of truth), uses a keyword trigger (jev), contains no secrets, and stays vendor-focused per the authoring rules inAGENTS.md. - Upstream accuracy: all 14 links in SKILL.md return HTTP 200. The Python example matches the live upstream SDK docs:
TypeSafeClient(*, api_key: str | None = None, ...),client.system_one(state=..., questions=...), andresult.choices/scores/noulsall exist in the releasedtypesafe-sdkAPI. UsingJEV_API_KEYpassed explicitly asapi_keyis valid (explicit options take precedence over env vars upstream) and is required by the linked issue. - Registry plumbing: marketplace entry,
skills/index.jsentry, and README catalog counts (72 → 73 extensions) are consistent;.plugin/plugin.jsoncarries the required fields (name,description,author,version) enforced bytests/test_skill_plugin_loading.py; vendor symlinks (.claude-plugin,.codex-plugin) are present and match the pattern used by every other skill. - Generated SDK reference: the
skills/openhands-sdk/SKILL.mdrefresh is the sanctioned path (auto-generated byscripts/sync_openhands_sdk_skill.py), and thesync-sdk-skillCI check passes on this head. - CI: all checks green on
02ee7c8(test,sync-extensions,sync-sdk-skill,validate-claude-code, PR gates).
Acceptance criteria (from #618):
- SKILL.md has Jev intro, upstream links, three primitive examples,
jevtrigger - Example reads
JEV_API_KEYand passes it as the client'sapi_keyargument - Registered in marketplace + generated catalog, valid plugin metadata, README symlink (symlink is explicitly required by the issue; note GitHub renders it as the literal text
SKILL.mdrather than file content - non-blocking, matches the issue's intent) - No duplicate skill license or copied upstream manual
- Catalog, plugin loading, README, and generated reference checks pass (verified via CI on this head)
Repository fit: a reusable public skill is exactly what this registry owns; no cross-repo boundary concerns.
[RISK ASSESSMENT] LOW - documentation-only skill addition with no executable code paths in this repo; the only runtime surface is an example snippet verified against upstream docs, and it reads the API key from the environment rather than embedding it.
Verdict: APPROVE. Key insight: the skill correctly delegates truth to upstream (llms.txt and linked pages) instead of copying documentation into the registry, which keeps the maintenance burden near zero as Jev's docs evolve.
Updated instructions to ensure JEV_API_KEY is provided by the user if not set.
|
@OpenHands check why CI fails please and fix it |
|
I'm on it! enyst can track my progress at all-hands.dev |
Regenerate skills/index.js after the Jev API-key guidance edit so the catalog freshness test passes. Co-authored-by: openhands <openhands@all-hands.dev>
|
Fixed in 491bb41. The failure was Validation:
This comment was generated by an AI agent (OpenHands) on behalf of @enyst. |
|
Fixed and pushed commit Cause: The Jev skill’s API-key guidance changed, but the generated Fix: Regenerated the catalog. No workflow or test changes were needed. Verification: All 9 applicable CI checks pass. Full test suite: 958 passed, 24 skipped. Posted the diagnosis and results on the PR. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope: in-repo. A reusable public skill belongs in this registry, and the change follows the authoring rules in AGENTS.md (one skill per directory, progressive disclosure, upstream docs as source of truth, keyword trigger, no secrets, marketplace + catalog registration). No cross-repo or product-direction concern.
Verified on head 491bb417a623bae2b0b5b7fa6e14441ff0630afa:
- Content correctness (strongest signal): I installed the released
typesafe-sdk(0.7.1) and validated the example against the real API.Choice/Score/Noultakeinstructions+criteriawith exactly the shapes used here;TypeSafeClientacceptsapi_key;client.system_one(state=..., questions=...)exists; andresult.choices["..."].choice,result.scores["..."].score,result.nouls["..."].noulare all real accessors. The snippet runs to the auth boundary and fails only on the dummy key (TypeSafeAuthenticationError), so the code path is correct. All 14 upstream links return HTTP 200. - Registry plumbing: marketplace entry,
skills/index.js, and README catalog counts are consistent;.plugin/plugin.jsonhas the fields enforced bytests/test_skill_plugin_loading.py; vendor symlinks and theREADME.mdsymlink match the issue's stated requirements. - Tests:
uv run pytest -q tests/test_skills_have_readme.py tests/test_skill_plugin_loading.py tests/test_skills_catalog.py-> 131 passed locally. All GitHub Actions checks are green on this head (test,check,sync-extensions,sync-sdk-skill,validate-claude-code, PR gates).
Material finding - this branch cannot be merged as-is.
GitHub reports mergeable: false / mergeable_state: dirty. I reproduced the conflicts against the current main (f02d3aa) with git merge-tree: README.md, marketplaces/openhands-extensions.json, and skills/index.js all conflict. These are generated files, and main has advanced past this branch's merge-base with two added skills (canvas-extension-api, github-stale-ci-pr-closer) plus releases 0.23.0/0.24.0. The PR needs a rebase onto current main followed by regenerating the derived artifacts (npm run build:skills, python scripts/sync_extensions.py). Without this the PR will not merge.
Non-blocking note on generated content: re-running uv run python scripts/sync_openhands_sdk_skill.py --check on this head now fails because the docs site gained a new SDK example after this head's CI ran. That is upstream drift, not a defect introduced here, but the SDK reference should be refreshed during the rebase so the sync-sdk-skill check stays green.
Non-blocking note on JEV_API_KEY: the upstream SDK's own default env var is TYPESAFE_API_KEY; JEV_API_KEY appears nowhere in the upstream docs. The example is still correct because it passes the value explicitly via api_key= (verified: explicit values take precedence), and the linked issue mandates JEV_API_KEY, so no change is required. Worth knowing that a user who only sets TYPESAFE_API_KEY will not have it picked up by this snippet.
Minor consistency (non-blocking): skills/use-jev/.plugin/plugin.json is the only manifest in the repo that omits "license": "MIT" (the other 73 declare it). No test enforces this and the linked issue only asked not to add a separate license file, so it does not block the merge.
Repository fit / risk: documentation-only addition, no executable paths merged into this repo; the only runtime surface is an example that reads a key from the environment rather than embedding it. Risk: LOW.
🔄 CHANGES REQUESTED
|
@enyst once the review bit is happy i'm also happy. Feel free to merge |
|
🚀 Released in v0.26.0. |
4 participants
HUMAN:
This PR proposes a small intro skill to Jev, so the agent knows where to get info from.
AGENT:
Why
Give OpenHands agents a concise introduction to Jev, a newly released general classifier, with upstream documentation as the source of truth.
Summary
use-jevskill triggered byjev, linking to upstream use cases, best practices, SDK/API docs, andllms.txt.JEV_API_KEY.Issue Number
Fixes #618.
How to Test
pytest -q tests/test_skills_have_readme.py tests/test_skill_plugin_loading.py tests/test_skills_catalog.py).npm run build:skillsandpython scripts/sync_extensions.py --checkpass. Existing unrelated catalog coverage warnings remain.python scripts/sync_openhands_sdk_skill.py --checkpasses after regeneration.Jev-Fast-Audit
⚡ Jev fast audit · estimates · 0.49s · commit c8e31a7⚠️ reduced context — partial coverage; 10/10 hunks, 8/8 files (missing context: 4).
Strongest signal: No primary concern selected.
Evidence: No primary concern to locate.
Coverage:
All estimates and evidence