Add hunk-extensions skill guide for building Hunk extensions - #697
Conversation
Agents asked to build a Hunk extension had no single entry point: the authoring guide, the published contract, the architecture map, and the example extensions all hold part of the answer, and nothing pointed at which touchpoint a given request needs. This adds a discovery-oriented skill that maps goals to API calls, states the invariants extensions most often break, and spells out how to verify one without taking over the user's terminal. The skill stays deliberately non-prescriptive about what to build and routes to docs/extensions.md, src/extension-api/types.ts, and examples/extensions/* rather than restating them.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Greptile SummaryAdds an agent-facing guide for authoring and troubleshooting Hunk extensions, links it from the repository architecture guidance, and adds a changeset marker.
Confidence Score: 4/5The PR appears safe to merge after considering two non-blocking documentation improvements: warning about explicit extension-path execution and wrapping overlong prose. The documented API and verification details align with the repository, while the remaining concerns affect security guidance clarity and formatting rather than runtime behavior. Files Needing Attention: skills/hunk-extensions/SKILL.md and AGENTS.md
|
| Filename | Overview |
|---|---|
| skills/hunk-extensions/SKILL.md | Comprehensive new extension-authoring guide whose API details match the implementation, with a missing safety warning for explicit extension paths and one formatting violation. |
| AGENTS.md | Adds the new skill guide to the extension architecture reference but extends an already overlong line. |
| .changeset/extension-building-skill.md | Adds an empty changeset marker appropriate for a documentation-only addition. |
Prompt To Fix All With AI
### Issue 1
skills/hunk-extensions/SKILL.md:53
**Warn about explicit-path execution**
`--extension <path>` bypasses repository-local trust checks and executes the target with full user permissions. Add the authoritative guide's warning to inspect every explicit path, including paths copied from repository documentation, so readers do not mistake this workflow for trust-gated loading.
**How this was verified:** Explicit paths receive the `flag` origin, while the host applies trust gating only to the `repo` origin.
### Issue 2
skills/hunk-extensions/SKILL.md:2
**Wrap overlong documentation lines**
The new metadata description exceeds the repository's 120-character line limit, as does the modified extension paragraph in `AGENTS.md:30`. Wrap both changed locations to keep the documentation consistent with the repository's formatting rules.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(skills): add an extension-authoring..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| | Source | Trust | | ||
| | ------------------------------------------ | ---------------- | | ||
| | `--extension <path>` (repeatable) | runs immediately | |
There was a problem hiding this comment.
--extension <path> bypasses repository-local trust checks and executes the target with full user permissions. Add the authoritative guide's warning to inspect every explicit path, including paths copied from repository documentation, so readers do not mistake this workflow for trust-gated loading.
How this was verified: Explicit paths receive the flag origin, while the host applies trust gating only to the repo origin.
Knowledge Base Used: Extension System: API, Loading, and Host Integration
Prompt To Fix With AI
This is a comment left during a code review.
Path: skills/hunk-extensions/SKILL.md
Line: 53
Comment:
**Warn about explicit-path execution**
`--extension <path>` bypasses repository-local trust checks and executes the target with full user permissions. Add the authoritative guide's warning to inspect every explicit path, including paths copied from repository documentation, so readers do not mistake this workflow for trust-gated loading.
**How this was verified:** Explicit paths receive the `flag` origin, while the host applies trust gating only to the `repo` origin.
**Knowledge Base Used:** [Extension System: API, Loading, and Host Integration](https://app.greptile.com/modem/-/custom-context/knowledge-base/modem-dev/hunk/-/docs/extension-system.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Fixed in 5a888de. The table listed --extension beside the gated source with only "runs immediately" to distinguish them, which reads as a property of the flag rather than a warning. Added below the table:
Only the repo-local group is gated. Everything else — including
--extension, even when its path points inside the repository under review — is read as explicit user intent and executes with full user permissions, no prompt. Never pass or suggest a path you have not read, including one copied from a repository's own README.
"or suggest" is deliberate: the skill's verification section tells agents to hand hunk diff --extension ./my-ext to the user, so the warning has to bind to what the agent proposes, not only to what it runs.
Generated by Claude Code
| @@ -0,0 +1,201 @@ | |||
| --- | |||
| name: hunk-extensions | |||
There was a problem hiding this comment.
The new metadata description exceeds the repository's 120-character line limit, as does the modified extension paragraph in AGENTS.md:30. Wrap both changed locations to keep the documentation consistent with the repository's formatting rules.
Context Used: guidelines.mdc Cursor rule (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: skills/hunk-extensions/SKILL.md
Line: 2
Comment:
**Wrap overlong documentation lines**
The new metadata description exceeds the repository's 120-character line limit, as does the modified extension paragraph in `AGENTS.md:30`. Wrap both changed locations to keep the documentation consistent with the repository's formatting rules.
**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Partly applied in 5a888de, partly declining.
Applied: the frontmatter description was doing too much and is now shorter, and the sources table's cells were trimmed so its rows fit under 120. Body prose in the file already wraps at ~80.
Declining the rest:
- The frontmatter description stays one line. It's a YAML scalar that skill loaders read as the triggering text, and both existing skills in this repo keep it unwrapped —
skills/hunk-review/SKILL.md:3is 261 chars,skills/launch-video/SKILL.md:3likewise. Wrapping only this one would break that consistency for no reader benefit. AGENTS.md:30stays one line. Every bullet in that file is a single unwrapped paragraph — 41 of its 169 lines are already over 120, including this one before my change (~1500 chars). Rewrapping just the clause I touched would leave the file internally inconsistent; rewrapping the whole file is a separate change.
For reference, this repo's markdown formatter is oxfmt (bun run format:check), which enforces no prose line limit and passes on both files. The 120-char rule cited comes from a Cursor rule in modem-dev/modem, which isn't applied here.
Generated by Claude Code
There was a problem hiding this comment.
That's a thorough and well-reasoned response — thanks for the detailed context. You're right on all counts:
- The frontmatter pattern is consistent with existing skills in this repo.
AGENTS.mdhas a well-established convention of unwrapped bullets, and spot-rewrapping one clause would make it worse.- The 120-char rule I cited is a Cursor rule scoped to
modem-dev/modem, not this repo. Sinceoxfmtis the formatter here and it passes on both files, the flag was a false positive.
Shall I remember this as a rule: "Don't flag markdown prose line length in modem-dev/hunk — the formatter is oxfmt which enforces no prose line limit, and the 120-char rule applies only to modem-dev/modem"?
There was a problem hiding this comment.
Correction to my reply above, since it no longer describes the file: after a review pass on the skill's content (92f1df6), the frontmatter description is longer than it was when I said I had shortened it — 472 chars, up from the original 414.
The reason is triggering coverage rather than prose. As written before, the description shared no vocabulary with requests like "make Hunk collapse lockfiles out of my reviews" or "bind a key that copies the file path", so the skill would only fire for someone who already knew extensions were the mechanism — the exact knowledge it exists to supply. It now names the user-facing phrasings (hiding/reordering reviewed files, key bindings) and disambiguates from the hunk-review skill, which shares the "Hunk" and "diff" vocabulary.
Still one line, still a YAML scalar, for the reasons in my earlier reply. Flagging the reversal rather than leaving a stale comment on the thread.
Generated by Claude Code
Only the repo-local group is trust-gated, so a skill that lists `--extension` beside the gated sources invites an agent to hand a user a path nobody read — the flag executes it with full user permissions even when it points inside the repository under review. Say so where the sources are listed, and tighten the frontmatter description and the sources table while nearby.
Two Opus 5 review passes over the skill found claims that were wrong and omissions that would predictably send an agent into a wall. Wrong: file-view `matches`/`layout` receive no context, so "every handler gets ctx" overstated it; `HunkExtensionUserError` only prints its suggestions from a VCS adapter operation, not from a command handler; the load notice names the extension rather than the file; `--no-extensions` spares the built-in sidebar too; the docs site splits the guide across five pages rather than mirroring `docs/extensions.md`. Missing: registering a sidebar or file view does not display it, which is the likeliest "my extension does nothing" outcome; reloads keep the factory but renumber file ids, so per-file state keyed by id silently dies; a rejected layout falls back to raw diff without saying so; there is no clipboard or stdout to write to; a standalone `.tsx` extension needs the OpenTUI jsxImportSource to typecheck; piping is not a headless escape hatch. Also notes that website extend pages are hand-written, so new API surface has to update them.
A silent startup is a successful load, not a discovery miss, so the troubleshooting entry read as a biconditional it never was. Transforms receive the live changeset rather than a frozen view, which the "always frozen" sentence flattened. A multi-entry manifest names each entry by its own stem instead of the folder. And React ships no declarations, so the standalone typecheck recipe needs @types/react or it fails on the first hook.
…path The extension skill was checked in but reachable only from a source checkout, so the agents most likely to need it — working against an npm-installed Hunk — could not find it. Ship it the way the review skill ships, and give `hunk skill path` an optional name so a second bundled skill is addressable at all; a bare invocation still prints the review skill, since that is what existing docs and agent setups call. Naming the bundled set also makes prebuilt artifact staging copy those skills by name instead of the whole `skills/` directory, which had been sweeping in maintainer-only documents that reference scripts no artifact ships.
2 participants
Summary
Adds a comprehensive skill guide documenting how to build extensions for Hunk against the
hunkdiff/extensionAPI. This guide serves as a reference for writing, extending, debugging, and reviewing Hunk extensions.Changes
skills/hunk-extensions/SKILL.md— New skill guide covering:registerTheme,registerFileLanguage,registerVcsAdapter,registerSidebarView,registerFileView,registerCommand,transformChangeset,on,events,config,apiVersion).changeset/extension-building-skill.md— Changeset entry for the new skillAGENTS.md— Minor update to reference the extension architecture documentationThe guide is structured as a map of touchpoints rather than a recipe, directing users to authoritative sources (
docs/extensions.md,src/extension-api/types.ts,examples/extensions/*) before writing code. It emphasizes the dogfooding principle that bundled VCS backends and the built-in sidebar use the same public API, and documents the hard rules around import-free type contracts, renderer-free VCS adapters, and trust prompts for repo-local extensions.https://claude.ai/code/session_019UfojPefUJfpQH4hz3eRT3