Skip to content

docs(code-review): add integrations section pointing to open-code-review#327

Open
lizhengfeng101 wants to merge 3 commits into
addyosmani:mainfrom
lizhengfeng101:feat/open-code-review-skill
Open

docs(code-review): add integrations section pointing to open-code-review#327
lizhengfeng101 wants to merge 3 commits into
addyosmani:mainfrom
lizhengfeng101:feat/open-code-review-skill

Conversation

@lizhengfeng101

@lizhengfeng101 lizhengfeng101 commented Jun 25, 2026

Copy link
Copy Markdown

Summary

Instead of adding a standalone skill, this adds a lightweight "Integrations" subsection under "See Also" in code-review-and-quality/SKILL.md, pointing users to the Open Code Review CLI and its Claude Code skill for tool-augmented review on large changesets.

This follows the alternative approach suggested by @nucliweb in #327 (comment) — keeping the pack self-contained and zero-dependency while still letting users discover additional tooling.

Changes

  • Added an "Integrations" subsection under "See Also" in skills/code-review-and-quality/SKILL.md
  • Removed the standalone skills/open-code-review/ directory
  • Reverted all changes to README.md, AGENTS.md, and docs/getting-started.md

@nucliweb

Copy link
Copy Markdown
Contributor

Thanks for this, the skill itself is well-crafted and the underlying tool looks genuinely solid. Before it goes further I want to raise a scope question that I think is the real decision here, and it is ultimately a maintainer call.

My concern is fit, not quality. The skills in this pack encode a process, a tool-agnostic way a senior engineer approaches a task. This skill is a different genre: it teaches the agent to operate one specific vendor CLI and format its output. The review intelligence lives inside ocr, not in the skill, so what we would be adding is essentially a usage manual plus an output formatter for a third-party product.

Three things make me lean against adding it as a first-class skill:

  1. It overlaps with code-review-and-quality and frames it as the lesser option. The skill's core message is "the built-in review is only good enough for small changes, install this external tool for real work." Positioning one of the pack's own skills as inferior to a third party reads, even if unintentionally, as promotion.
  2. Maintenance coupling. The skill is tied to another project's CLI surface (--audience agent, ocr config, env vars). When that interface changes, the skill rots, and a pack that sells itself as self-contained and zero-dependency inherits the cost of documenting someone else's tool.
  3. The vendor already ships this. open-code-review is distributed as a Claude Code plugin and skill by its own authors, so re-hosting it here is redundant, and it invites the same request for every other third-party review CLI, which dilutes what makes this pack distinctive.

The browser-testing-with-devtools precedent does not quite apply: DevTools gives the agent a capability it otherwise lacks (observing a running browser), whereas this is a different vendor's take on a job an existing skill already covers.

That said, the insight behind the tool is worth keeping. The failure mode it targets is real: prompt-only agents do skip files on large changesets and drift on line numbers. A lighter-touch way to capture that without taking on a vendor dependency would be a short "See also / Integrations" note in code-review-and-quality pointing to ocr (and to the authors' own skill) for teams that want tool-augmented review. Happy to help shape that if it is useful.

(Separately and minor: the description uses a YAML folded scalar >, which the repo's frontmatter parser does not handle, so the validator currently reads it as a single character rather than the real text. Worth switching to a plain single-line description regardless of the outcome above.)

@lizhengfeng101

Copy link
Copy Markdown
Author

Thank you for the thoughtful and detailed feedback, @nucliweb — really appreciate you taking the time to lay out the reasoning so clearly.

We want to sincerely apologize if our description came across as positioning code-review-and-quality as a lesser option. That was never our intention, and we're sorry for the impression it gave. The built-in skill is excellent on its own, and we have great respect for the work that's gone into this pack.

We fully accept the suggested alternative approach. A short "See also / Integrations" note in code-review-and-quality pointing to ocr and our own skill/plugin sounds like the right fit — it keeps the pack self-contained while still letting users discover additional tooling if they want it. The goal has always been to give users more choices with a low barrier to entry, and a pointer achieves that without the maintenance coupling or scope concerns you raised.

We'll close this PR accordingly. If there's anything we can do to help shape that integrations note, happy to contribute.

lizhengfeng101 added a commit to lizhengfeng101/agent-skills that referenced this pull request Jun 26, 2026
The tool is now referenced as an integration in code-review-and-quality
instead of being a separate skill, per reviewer feedback on addyosmani#327.
@lizhengfeng101 lizhengfeng101 changed the title feat: add open-code-review skill for tool-augmented code review docs(code-review): add integrations section pointing to open-code-review Jun 26, 2026
Add a new skill that integrates alibaba/open-code-review (ocr) CLI
into the agent-skills workflow. This complements the existing
code-review-and-quality skill with a tool-augmented approach that
combines deterministic engineering with an LLM agent for higher
precision at ~1/9 token cost.
Instead of adding a standalone skill, add a lightweight "Integrations"
note under See Also in code-review-and-quality, pointing users to the
ocr CLI and its Claude Code skill for tool-augmented review on large
changesets.
The tool is now referenced as an integration in code-review-and-quality
instead of being a separate skill, per reviewer feedback on addyosmani#327.
@lizhengfeng101 lizhengfeng101 force-pushed the feat/open-code-review-skill branch from 99f3287 to cc30f17 Compare June 29, 2026 07:43
@lizhengfeng101

Copy link
Copy Markdown
Author

Hi @nucliweb 👋

Thanks again for the excellent feedback on the original approach — it was spot on.

We've reworked this PR to follow the alternative you suggested: a short Integrations section in code-review-and-quality/SKILL.md that points users to ocr as a tool-augmented option for large changesets. No standalone skill, no vendor dependency, just a lightweight pointer.

We also rebased onto the latest main to resolve the merge conflict that had come up.

Would you be able to take another look when you get a chance? Happy to adjust anything if the wording or placement needs tweaking. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants