chore(ai): migrate guidance into skills - #1003
Conversation
Move reusable CLAUDE.md guidance into repo-local skills so agents can load task-specific instructions instead of carrying the full repository guide in context. Make .agents/skills the canonical skill source and sync .claude/skills as symlinks, matching the rorkai layout. The sync script now validates and creates symlinks from .agents to .claude. Document the unified ccusage command surface for agent CLIs and mark standalone agent binaries as deprecated compatibility wrappers.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR centralizes skills under ChangesSkills Architecture and Documentation
Sequence Diagram(s)No additional sequence diagrams beyond the embedded sync script diagram in the hidden review stack. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
@ccusage/amp
ccusage
@ccusage/codex
@ccusage/opencode
@ccusage/pi
commit: |
ccusage performance comparisonThis compares the PR build against the base branch build on the same CI runner. Committed fixture performanceCommitted small fixture for stable PR-to-PR feedback and output-shape regressions. Fixture:
Large real-world-shaped fixture performanceGenerated fixture around 1 GiB shaped from aggregate local Claude-log statistics: thousands of JSONL files, many small sessions, and a long tail of larger sessions. No real prompts, paths, or outputs are stored in the fixture. Fixture:
Package size
Lower medians and smaller packed package sizes are better. CI runner noise still applies; use same-run ratios as directional PR feedback, not release guarantees. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/ccusage-development/SKILL.md:
- Around line 77-83: Update the SKILL.md instructions so formatting is run
before any mutating checks: replace the current "run these in parallel" wording
with a sequential recommendation to run `pnpm run format` first, then `pnpm
typecheck` and `pnpm run test` (noting that `pnpm typecheck` and `pnpm run test`
may be run in parallel if desired); specifically edit the block containing the
`pnpm run format`, `pnpm typecheck`, and `pnpm run test` commands to reflect
this ordering and rationale.
In @.agents/skills/commit/SKILL.md:
- Around line 129-135: Update the fenced code blocks flagged by MD040 to include
a language identifier (e.g., add "text" or "gitcommit" after the opening ```),
specifically for the example blocks that contain the commit messages such as
"feat(auth): add RefreshTokenService class" and "feat(auth): integrate token
rotation in middleware" (also apply the same change to the other fenced examples
referenced around lines 159-173); ensure every opening ``` has ```text so
markdownlint no longer reports missing language identifiers.
In @.agents/skills/tdd/SKILL.md:
- Around line 17-23: Add a language tag to the two fenced command-output blocks
so markdownlint MD040 is satisfied: change the fences around the block starting
with !`cat package.json 2>/dev/null | jq -r '.scripts ...'` and the block
starting with !`if [ -f vitest.config.ts ] || [ -f vitest.config.js ] ...` to
use ```bash instead of plain ```, keeping the command text unchanged and leaving
other fences in the file as-is.
In @.agents/skills/tdd/vitest-example.md:
- Around line 18-30: Replace the non-canonical usage it.extend({...}) with the
canonical test.extend({...}) and add test to the list of Vitest globals so
examples and guidance use the official API; update the globals declaration (the
globals array/list that currently mentions describe, it, expect, vi, beforeEach,
assert) to include test and change any example uses of it.extend to test.extend
to maintain consistency with Vitest docs and tooling.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c1eb3dbb-65b6-4889-9afa-c0f92a8ff88f
📒 Files selected for processing (43)
.agents/skills/bun-api-reference/SKILL.md.agents/skills/bun-cpu-profile.agents/skills/bun-cpu-profile/SKILL.md.agents/skills/bun-cpu-profile/agents/openai.yaml.agents/skills/byethrow.agents/skills/byethrow/SKILL.md.agents/skills/ccusage-agent-sources/SKILL.md.agents/skills/ccusage-development/SKILL.md.agents/skills/ccusage-docs/SKILL.md.agents/skills/ccusage-testing/SKILL.md.agents/skills/cmux-debug.agents/skills/cmux-debug/SKILL.md.agents/skills/commit/SKILL.md.agents/skills/fs-fixture/SKILL.md.agents/skills/reduce-similarities.agents/skills/reduce-similarities/SKILL.md.agents/skills/tdd/SKILL.md.agents/skills/tdd/vitest-example.md.agents/skills/typescript-style/SKILL.md.agents/skills/use-gunshi-cli.agents/skills/use-gunshi-cli/SKILL.md.claude/skills/bun-api-reference.claude/skills/bun-cpu-profile.claude/skills/byethrow.claude/skills/ccusage-agent-sources.claude/skills/ccusage-development.claude/skills/ccusage-docs.claude/skills/ccusage-testing.claude/skills/cmux-debug.claude/skills/commit.claude/skills/fs-fixture.claude/skills/reduce-similarities.claude/skills/tdd.claude/skills/typescript-style.claude/skills/use-gunshi-cliCLAUDE.mdapps/amp/CLAUDE.mdapps/ccusage/CLAUDE.mdapps/codex/CLAUDE.mdapps/opencode/CLAUDE.mdapps/pi/CLAUDE.mddocs/CLAUDE.mdscripts/sync-skills.ts
💤 Files with no reviewable changes (5)
- .agents/skills/byethrow
- .agents/skills/cmux-debug
- .agents/skills/use-gunshi-cli
- .agents/skills/reduce-similarities
- .agents/skills/bun-cpu-profile
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
7 issues found across 43 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".agents/skills/ccusage-agent-sources/SKILL.md">
<violation number="1" location=".agents/skills/ccusage-agent-sources/SKILL.md:90">
P2: The OpenCode source description is outdated: messages are loaded from SQLite databases (`opencode.db` / `opencode-*.db`) and JSON files are only a fallback. Documenting JSON files as the only source can lead to incorrect parser/test updates.</violation>
</file>
<file name=".agents/skills/ccusage-development/SKILL.md">
<violation number="1" location=".agents/skills/ccusage-development/SKILL.md:48">
P2: These `pnpm run start ...` examples are presented as root-level commands, but the root workspace has no `start` script. Use a workspace filter (or explicitly scope to `apps/ccusage`) so they work from repo root.</violation>
<violation number="2" location=".agents/skills/ccusage-development/SKILL.md:73">
P2: This dependency rule is too broad for deprecated wrapper apps that must keep install-time runtime deps (for example `ccusage`) in `dependencies`. Narrow the rule to avoid breaking wrapper package installs.
(Based on your team's feedback about wrapper packages requiring `ccusage` in `dependencies`.) [FEEDBACK_USED]</violation>
<violation number="3" location=".agents/skills/ccusage-development/SKILL.md:77">
P2: Avoid running `pnpm run format` in parallel with `typecheck` and `test`. `format` mutates files, so concurrent checks can read changing content and produce flaky or inconsistent results.</violation>
</file>
<file name=".agents/skills/tdd/SKILL.md">
<violation number="1" location=".agents/skills/tdd/SKILL.md:22">
P2: The pytest detection condition is incorrectly grouped, so repositories with `pytest.ini` can be misdetected as not using pytest.</violation>
<violation number="2" location=".agents/skills/tdd/SKILL.md:61">
P2: This section points to `rust-example.md` and `zig-example.md`, but those files do not exist in the repository.</violation>
</file>
<file name=".agents/skills/commit/SKILL.md">
<violation number="1" location=".agents/skills/commit/SKILL.md:40">
P1: Resetting the full file before applying a single-hunk patch can discard other pending hunks from that file. Stage the patch directly instead so remaining changes are preserved for later commits.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.
Re-trigger cubic
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ⛔ Deployment terminated View logs |
ccusage-guide | affb635 | May 16 2026, 01:31 PM |
|
@coderabbitai review |
@ryoppippi I have started the AI code review. It will take a few minutes to complete. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 43433
OverviewThe migration cleanly separates concerns: Issue 1 —
|
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
.agents/skills/ccusage-development/SKILL.md (1)
77-83:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAvoid recommending parallel execution for mutating checks.
Running
pnpm run formatin parallel withtypecheck/testcan cause flaky or inconsistent results because formatting changes files during other checks. Recommend sequential wording (format first, then typecheck/test in parallel if desired).Suggested wording
-After code changes, run these in parallel: +After code changes, run: ```sh pnpm run format pnpm typecheck pnpm run testOptionally add a note: "Run `pnpm run format` first; `typecheck` and `test` may be run in parallel afterward." </details> Based on learnings: "After code changes, run `pnpm run format`, `pnpm typecheck`, and `pnpm run test`." <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In @.agents/skills/ccusage-development/SKILL.md around lines 77 - 83, Update the
wording that currently suggests running "pnpm run format", "pnpm typecheck", and
"pnpm run test" in parallel: change it to instruct running "pnpm run format"
first (since it mutates files), then run "pnpm typecheck" and "pnpm run test"
afterward — and note that those two may be executed in parallel if desired;
ensure the commands "pnpm run format", "pnpm typecheck", and "pnpm run test" are
explicitly mentioned in the revised sentence for clarity.</details> </blockquote></details> <details> <summary>.agents/skills/commit/SKILL.md (1)</summary><blockquote> `131-137`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add language identifiers to fenced code blocks.** Markdownlint flags these code fences as missing language identifiers. Adding `text` or `gitcommit` will clear warnings and keep docs lint-clean. <details> <summary>Suggested fix</summary> ```diff -``` +```text <type>(<scope>): <subject> <body> <footer>Apply the same change to the example blocks at lines 161 and 169: ```diff -``` +```text feat(auth): add RefreshTokenService class Added new RefreshTokenService to handle token lifecycle management. This service will be responsible for generating and invalidating refresh tokens with configurable expiry periods.-
+text
feat(auth): integrate token rotation in middlewareUpdated auth middleware to call RefreshTokenService when validating
tokens. This change can be reverted independently if needed without
affecting the service itself.Also applies to: 159-175
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/commit/SKILL.md around lines 131 - 137, Add a language identifier (e.g., text or gitcommit) to the fenced code blocks in the commit examples so they pass markdownlint; update the generic commit template block (the triple-backtick block containing "<type>(<scope>): <subject>") and the example blocks that start with "feat(auth): add RefreshTokenService class" and "feat(auth): integrate token rotation in middleware" to use ```text (or ```gitcommit) instead of bare ``` so lint warnings are cleared.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/commit/SKILL.md:
- Line 36: Update the skill documentation to use US English by replacing the
phrase "Analyse the changes above" with "Analyze the changes above" (and scan
the rest of .agents/skills/commit/SKILL.md for other UK spellings); keep the
existing note that line 179 allows UK English for commit messages but ensure the
skill documentation text itself follows US spelling conventions.
---
Duplicate comments:
In @.agents/skills/ccusage-development/SKILL.md:
- Around line 77-83: Update the wording that currently suggests running "pnpm
run format", "pnpm typecheck", and "pnpm run test" in parallel: change it to
instruct running "pnpm run format" first (since it mutates files), then run
"pnpm typecheck" and "pnpm run test" afterward — and note that those two may be
executed in parallel if desired; ensure the commands "pnpm run format", "pnpm
typecheck", and "pnpm run test" are explicitly mentioned in the revised sentence
for clarity.
In @.agents/skills/commit/SKILL.md:
- Around line 131-137: Add a language identifier (e.g., text or gitcommit) to
the fenced code blocks in the commit examples so they pass markdownlint; update
the generic commit template block (the triple-backtick block containing
"<type>(<scope>): <subject>") and the example blocks that start with
"feat(auth): add RefreshTokenService class" and "feat(auth): integrate token
rotation in middleware" to use ```text (or ```gitcommit) instead of bare ``` so
lint warnings are cleared.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7a770481-c202-4bda-8b5f-06fb575062ba
📒 Files selected for processing (5)
.agents/skills/ccusage-development/SKILL.md.agents/skills/commit/SKILL.md.agents/skills/pr-ai-review-workflow/SKILL.md.claude/skills/pr-ai-review-workflowCLAUDE.md
✅ Files skipped from review due to trivial changes (2)
- .claude/skills/pr-ai-review-workflow
- CLAUDE.md
There was a problem hiding this comment.
6 issues found across 45 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".agents/skills/tdd/SKILL.md">
<violation number="1" location=".agents/skills/tdd/SKILL.md:22">
P2: The pytest detection condition has incorrect boolean grouping, so repos with only `pytest.ini` are misdetected as `unknown`.</violation>
</file>
<file name=".agents/skills/ccusage-development/SKILL.md">
<violation number="1" location=".agents/skills/ccusage-development/SKILL.md:48">
P2: The documented `pnpm run start ...` examples are invalid at repo root because root `package.json` has no `start` script.</violation>
</file>
<file name=".agents/skills/pr-ai-review-workflow/SKILL.md">
<violation number="1" location=".agents/skills/pr-ai-review-workflow/SKILL.md:60">
P2: The reviewThreads query is not paginated, so it can miss comments beyond the first 100 threads.</violation>
<violation number="2" location=".agents/skills/pr-ai-review-workflow/SKILL.md:95">
P2: The inline review reply endpoint is incorrect; it must include `<pull_number>` in the path.</violation>
</file>
<file name=".agents/skills/ccusage-agent-sources/SKILL.md">
<violation number="1" location=".agents/skills/ccusage-agent-sources/SKILL.md:157">
P2: This dependency guidance is too broad for deprecated wrapper packages: those wrappers resolve `ccusage` at runtime, so `ccusage` must stay in `dependencies`.
(Based on your team's feedback about keeping `ccusage` in dependencies for deprecated runtime wrappers.) [FEEDBACK_USED]</violation>
</file>
<file name=".agents/skills/commit/SKILL.md">
<violation number="1" location=".agents/skills/commit/SKILL.md:201">
P1: The push workflow should enforce the "never push main" rule before executing `git push`; currently it can still push directly to `main` when upstream is configured.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Re-trigger cubic
|
Fixed the spell-check failure in 775b9c4. Local validation: direnv exec . typos --config ./typos.toml; pnpm run sync:skills:check. |
There was a problem hiding this comment.
3 issues found across 58 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".agents/skills/pr-ai-review-workflow/references/gh-review-commands.md">
<violation number="1" location=".agents/skills/pr-ai-review-workflow/references/gh-review-commands.md:65">
P2: This query only reads the first 100 review threads, so large PRs can appear fully resolved while unresolved threads exist on later pages. Add pagination (`after` + `pageInfo`) or explicitly document that this command is partial.</violation>
</file>
<file name=".agents/skills/commit/SKILL.md">
<violation number="1" location=".agents/skills/commit/SKILL.md:18">
P2: The inline command syntax is malformed, so `git status --short` is unlikely to execute and the skill may miss current git-state context.</violation>
<violation number="2" location=".agents/skills/commit/SKILL.md:26">
P2: The inline command syntax is malformed, so `git log --oneline -10` is unlikely to execute and recent history context may be missing.</violation>
</file>
Partial review: This PR has more than 50 files, so cubic reviewed the highest-priority files first. During the trial, paid plans get a higher file limit.
You can try an ultrareview to bypass the file limit, comment @cubic-dev-ai ultrareview. Learn more.
Fix all with cubic | Re-trigger cubic
|
@coderabbitai review |
@ryoppippi I have started the AI code review. It will take a few minutes to complete. |
🧩 Analysis chain🏁 Script executed: Length of output: 16110
✅ Issue 1 —
|
There was a problem hiding this comment.
3 issues found across 58 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".agents/skills/ccusage-agent-sources/references/claude-code.md">
<violation number="1" location=".agents/skills/ccusage-agent-sources/references/claude-code.md:13">
P2: The documented Claude file shape is inconsistent with current session parsing behavior; session IDs are derived from a session directory, not a flat `{sessionId}.jsonl` path.</violation>
</file>
<file name=".agents/skills/ccusage-agent-sources/SKILL.md">
<violation number="1" location=".agents/skills/ccusage-agent-sources/SKILL.md:49">
P2: This dependency guidance is too broad and can break deprecated wrapper binaries. Wrapper runtime dependencies (for example `ccusage`) must remain in `dependencies`; only internal workspace runtime libraries should default to `devDependencies`.
(Based on your team's feedback about internal workspace deps vs deprecated wrapper package exceptions.) [FEEDBACK_USED]</violation>
</file>
<file name="apps/pi/CLAUDE.md">
<violation number="1" location="apps/pi/CLAUDE.md:18">
P3: The documented deprecated wrapper name is incorrect for this package (`ccusage-pi`). The actual compatibility wrapper binary here is `pi`, so this line can mislead docs/tests toward the wrong command.</violation>
</file>
Partial review: This PR has more than 50 files, so cubic reviewed the highest-priority files first. During the trial, paid plans get a higher file limit.
You can try an ultrareview to bypass the file limit, comment @cubic-dev-ai ultrareview. Learn more.
Fix all with cubic | Re-trigger cubic
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/commit/SKILL.md:
- Line 36: The SKILL.md references three missing docs which break links: create
the referenced files or remove/update the references; specifically add new files
named references/revertable-commits.md, references/git-apply.md, and
references/push.md with the intended guidance content (examples, commands, and
best-practices) or edit .agents/skills/commit/SKILL.md to point to existing docs
or inline the necessary guidance where the links appear; ensure the filenames
match the identifiers used in the file so the links resolve.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6feaa92d-4170-4513-b75e-1dd3acf4d991
📒 Files selected for processing (2)
.agents/skills/commit/SKILL.md.agents/skills/pr-ai-review-workflow/references/gh-review-commands.md
✅ Files skipped from review due to trivial changes (1)
- .agents/skills/pr-ai-review-workflow/references/gh-review-commands.md
|
@coderabbitai review |
@ryoppippi I have started the AI code review. It will take a few minutes to complete. |
🧩 Analysis chain🏁 Script executed: Length of output: 7925
✅ Issue 1 —
|
There was a problem hiding this comment.
No issues found across 58 files
You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact [email protected].
Partial review: This PR has more than 50 files, so cubic reviewed the highest-priority files first. During the trial, paid plans get a higher file limit.
You can try an ultrareview to bypass the file limit, comment @cubic-dev-ai ultrareview. Learn more.
Re-trigger cubic
Update the commit skill push reference so the executable push workflow checks the current branch before inspecting upstream state or running git push. This makes the documented push path enforce the existing never-push-main policy instead of relying only on the higher-level principle in SKILL.md.
|
@coderabbitai review |
@ryoppippi I have started the AI code review. It will take a few minutes to complete. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 7942
✅ Issue 1 —
|
Rename the repo-local similarity skill metadata to reduce-similarities so CLAUDE.md, the skill directory, and the Claude symlink all use the same loadable skill name. This avoids routing agents through the old check-similarity-ts name while keeping the similarity-ts tool description in the skill metadata.
|
@coderabbitai review |
@ryoppippi I have started the AI code review. It will take a few minutes to complete. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 9312
✅ Issue 1 —
|
1 participant
Summary
Notes
Validation
Summary by cubic
Migrates CLAUDE guidance into repo-local skills under
.agents/skills(symlinked to.claude/skills) and standardizes docs and commands on the unifiedccusage <agent>CLI. Adds focused skills and clarifies data sources, pricing, and dependency policy to reduce friction across dev, tests, and reviews.New Features
fix-ci), agent sources, Bun APIs/profiling, TypeScript style, docs, filesystem fixtures, and duplicate-code checks (reduce-similarities).Refactors
scripts/sync-skills.tsnow syncs.agents/skills→.claude/skillsand validates symlinks.CLAUDE.mdfiles to route to skills; mark standalone agent wrappers as deprecated in favor ofccusage <agent>.reduce-similaritiesacross skills and symlinks.git applyusage, statusline commands, review-thread pagination notes, correctedccusage-piwrapper name, and guarded commit push instructions to block pushes tomain/master.Written for commit affb635. Summary will update on new commits. Review in cubic
Summary by CodeRabbit
Documentation
Chores