Drafting some developer facing agent skills by sunxd3 · Pull Request #1027 · chalk-lab/Mooncake.jl

sunxd3 · 2026-03-05T09:24:41Z

These are set up for Claude Code at the moment, for other coding agents, you can just ask the coding agents to migrate the skills for themselves (for Codex CLI and many others .agents folder is the destination).

Evaluating the usefulness of Skills is still a very lively debated topic. And I don't claim the skills here are critical and in prime state yet. But give it a try, we can iterate fast.

CI Summary — GitHub Actions

Documentation Preview

Mooncake.jl documentation for PR #1027 is available at:
https://chalk-lab.github.io/Mooncake.jl/previews/PR1027/

Performance

Performance Ratio:
Ratio of time to compute gradient and time to compute function.
Warning: results are very approximate! See here for more context.

┌────────────────────────────┬──────────┬──────────┬─────────────┬─────────┬─────────────┬────────┐
│                      Label │   Primal │ Mooncake │ MooncakeFwd │  Zygote │ ReverseDiff │ Enzyme │
│                     String │   String │   String │      String │  String │      String │ String │
├────────────────────────────┼──────────┼──────────┼─────────────┼─────────┼─────────────┼────────┤
│                   sum_1000 │ 180.0 ns │     1.61 │        1.62 │   0.667 │        3.28 │   6.23 │
│                  _sum_1000 │ 952.0 ns │     6.83 │        1.02 │  3680.0 │        34.1 │   1.08 │
│               sum_sin_1000 │  7.35 μs │     3.49 │        1.45 │    1.56 │        9.47 │   1.73 │
│              _sum_sin_1000 │  6.25 μs │     3.77 │        1.92 │   243.0 │        11.3 │   2.09 │
│                   kron_sum │ 201.0 μs │     12.5 │        3.46 │    24.2 │       350.0 │   21.9 │
│              kron_view_sum │ 284.0 μs │     10.6 │        4.63 │    13.4 │       245.0 │   11.5 │
│      naive_map_sin_cos_exp │  2.63 μs │     2.71 │        1.49 │ missing │        5.93 │   1.92 │
│            map_sin_cos_exp │   2.7 μs │     3.24 │        1.81 │    1.91 │        4.89 │   2.36 │
│      broadcast_sin_cos_exp │  2.68 μs │     2.76 │        1.38 │     3.9 │        1.24 │   1.87 │
│                 simple_mlp │ 367.0 μs │     4.86 │        2.55 │    1.45 │        7.44 │   2.79 │
│                     gp_lml │ 205.0 μs │     12.1 │         3.5 │    11.6 │     missing │    7.0 │
│ turing_broadcast_benchmark │  2.17 ms │     4.55 │         2.8 │ missing │        24.3 │   1.86 │
│         large_single_block │ 410.0 ns │     5.11 │         2.0 │  4350.0 │        29.3 │    2.1 │
└────────────────────────────┴──────────┴──────────┴─────────────┴─────────┴─────────────┴────────┘

- Add SessionStart hook to install Julia for Claude Code on the web - Update Julia version to 1.12.5 (latest stable) - Add /ir-inspect skill with SKILL.md and ir_inspect.jl script - Add tests for the ir-inspect skill alongside the skill directory

Teaching skill that explains Mooncake's AD pipeline, tangent types, BBCode IR, rule system, and Julia compiler prerequisites. Integrates with ir-inspect to offer live demonstrations of each concept.

Replace encyclopedia-style inline summaries with actionable routing: each topic now directs Claude to read specific docs/source files before answering, then run a concrete ir-inspect demo. Add debugging and user-facing API topics.

Point to raw GitHub URLs for Julia's IRCode, BasicBlock, and AbstractInterpreter source so Claude can fetch them on demand.

Detects specialization widening (e.g. typeof(sum) → Function in Vararg), SROA/allocation failures from inlining barriers, and non-inlined small callees. Includes compare mode for side-by-side analysis of slow vs fast call variants. Motivated by issue #1020 where ir-inspect showed identical Mooncake IR but the entry-point had a 13x slowdown. Also adds a Limitations section to ir-inspect pointing users to perf-diagnose when IR looks correct but performance is poor.

Framework-agnostic skill that traces performance issues from observable symptoms down to decision points in Julia's compiler source code. Uses Codex for deep source analysis and produces structured root cause reports. Includes: - Source map routing 6 issue categories to 27 Julia compiler files - 8-step investigation playbook with Codex collaboration patterns - MWE templates for each category (specialization, inlining, SROA, etc.) - Version policy handling pre/post-1.12 compiler restructuring

Make the skill tool-agnostic — it now describes reading Julia source via local clone (Grep/Read) or WebFetch, without assuming any particular external AI tool is available.

Remove content specific to issue #1020 (Vararg+Function specialization): - source-map.md: replace detailed notcalled_func walkthrough and called bitmask chain with concise category-level file listings and search terms - investigation-playbook.md: replace hardcoded source chain example with generic format template, add all 6 categories to decision point hints - mwe-patterns.md: replace Mooncake function name in reduction example

github-actions · 2026-03-05T09:34:00Z

Mooncake.jl documentation for PR #1027 is available at:
https://chalk-lab.github.io/Mooncake.jl/previews/PR1027/

codecov · 2026-03-05T09:40:52Z

Codecov Report

❌ Patch coverage is 93.68932% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/skill_utils.jl	93.62%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!

github-actions · 2026-03-05T09:45:48Z

Performance Ratio:
Ratio of time to compute gradient and time to compute function.
Warning: results are very approximate! See here for more context.

┌────────────────────────────┬──────────┬──────────┬─────────────┬─────────┬─────────────┬────────┐
│                      Label │   Primal │ Mooncake │ MooncakeFwd │  Zygote │ ReverseDiff │ Enzyme │
│                     String │   String │   String │      String │  String │      String │ String │
├────────────────────────────┼──────────┼──────────┼─────────────┼─────────┼─────────────┼────────┤
│                   sum_1000 │ 170.0 ns │     1.59 │        1.65 │   0.706 │        3.42 │    6.6 │
│                  _sum_1000 │ 952.0 ns │      6.9 │        1.01 │  5310.0 │        33.6 │   1.08 │
│               sum_sin_1000 │  6.78 μs │     4.13 │        1.41 │     1.7 │        10.3 │   1.89 │
│              _sum_sin_1000 │  5.38 μs │     3.45 │        2.19 │   285.0 │        13.0 │   2.42 │
│                   kron_sum │ 205.0 μs │     11.8 │        3.46 │    14.1 │       322.0 │   22.6 │
│              kron_view_sum │ 291.0 μs │     10.4 │        4.68 │    12.9 │       270.0 │   13.6 │
│      naive_map_sin_cos_exp │  2.46 μs │     2.49 │        1.39 │ missing │         6.3 │   2.03 │
│            map_sin_cos_exp │  2.51 μs │     2.74 │        1.43 │    2.12 │        5.23 │   2.52 │
│      broadcast_sin_cos_exp │   2.6 μs │      2.5 │        1.36 │    4.59 │        1.28 │   1.92 │
│                 simple_mlp │ 350.0 μs │     4.77 │         2.8 │    1.51 │        8.26 │   2.87 │
│                     gp_lml │ 457.0 μs │     5.46 │        1.63 │    6.08 │     missing │   4.49 │
│ turing_broadcast_benchmark │  2.17 ms │     3.78 │        2.79 │ missing │        23.6 │   1.84 │
│         large_single_block │ 396.0 ns │     5.03 │         2.0 │  4740.0 │        31.2 │   2.18 │
└────────────────────────────┴──────────┴──────────┴─────────────┴─────────┴─────────────┴────────┘

@unstable

Move IR inspection and performance diagnostics code from .claude/skills/ scripts into src/skill_utils.jl (included as @unstable in Mooncake module). Move compiler-rootcause reference docs to docs/src/developer_documentation/, rewritten for human readers. Move tests to test/ with new "skill_utils" test group. Slim down SKILL.md files to reference src/ and docs/ instead of embedding code and docs inline. Deduplicate _count_allocs by reusing TestUtils.__count_allocs.

No longer needed — Claude Code on web now supports setup scripts directly.

- Consolidate 4 skills into 1 (ir-inspect), remove debug-compiler, mooncake-reference, perf-diagnose, compiler-rootcause - Consolidate 4 developer docs into 1 (advanced_debugging.md) - Convert skill_utils.jl into SkillUtils module following TestUtils pattern - Cut unreliable perf diagnostics code (~850 lines) and CFG/DOT generation - Remove unused InteractiveUtils and Printf deps - Fix world_age_info stale detection, show_ir notes display - Update tests and docs to use Mooncake.SkillUtils

@example

… Julia 1.11 - Convert plain julia code blocks to @example blocks in advanced_debugging.md - Add @unstable to skill_utils.jl include for DispatchDoctor compatibility - Add advanced_debugging.md to size_threshold_ignore in docs/make.jl

Remove OpaqueClosure/MistyClosure and compiler boundary investigation sections — not actionable debugging guidance. Revert unintended Project.toml formatting changes.

@example

- Add skill_utils to CI matrix (Julia 1.11) - Remove nothing # hide from doc @example blocks

Copilot

Pull request overview

Adds a new internal developer tool module (Mooncake.SkillUtils) for inspecting/diffing IR across Mooncake’s AD pipeline stages, wires it into docs, tests, and CI, and provides an accompanying Claude skill document.

Changes:

Introduce src/skill_utils.jl with IR inspection, stage rendering, diffs, and world-age reporting utilities.
Add a dedicated test group (skill_utils) and a CI matrix entry to run it.
Add “Advanced Debugging” docs explaining how to use IR inspection utilities.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`src/skill_utils.jl`	New internal IR inspection utilities and display/export helpers.
`src/Mooncake.jl`	Includes `skill_utils.jl` behind `@unstable`.
`test/skill_utils.jl`	New test coverage for `SkillUtils` functionality.
`test/runtests.jl`	Adds `skill_utils` test-group dispatch.
`.github/workflows/CI.yml`	Adds a CI job for the new `skill_utils` test group.
`docs/src/developer_documentation/advanced_debugging.md`	New developer-facing documentation for IR/world-age debugging.
`docs/make.jl`	Adds the new page to navigation and size-threshold ignore list.
`.claude/skills/ir-inspect/SKILL.md`	Adds a Claude Code skill guide for the new IR inspection tooling.

- Throw ArgumentError for invalid mode values instead of silent fallback - Document that world kwarg is diagnostic-only, not used for IR generation - Clarify that optimize/do_inline only affect the final optimization pass

yebai · 2026-03-26T17:43:25Z

I'll try to take a look over the weekend.

yebai

Looks good overall. I looked at the skill but skipped the code.

One minor suggestion, to avoid the layers of redirections, can we rename .claude/skills/ir-inspect/SKILL.md to .claude/skills/ir_inspect.md

yebai · 2026-03-30T15:46:37Z

+
+### Forward mode stages
+
+`:raw` → `:normalized` → `:bbcode` → `:dual_ir` → `:optimized`


Double check this, IIRC, forward mode only works with IRCode, not BBCode.

yebai · 2026-03-30T15:49:02Z

+- **`LazyDerivedRule` / `DynamicDerivedRule`**: these handle world age
+  transitions by recompiling on demand.


Double-check this, I'm not sure it's true. LazyDerivedRule is only an optimisation; instead of trying to handle world age issues, DynamicDerivedRule does help.

yebai · 2026-03-30T15:53:34Z

    elseif test_group == "rules/high_order_derivative_patches"
        include(joinpath("rules", "high_order_derivative_patches.jl"))
+    elseif test_group == "skill_utils"
+        include("skill_utils.jl")


This can probably be merged into the basic group to reduce the number of CI jobs.

* Fix IR inspection staging * Fix skill utils world guard

Co-authored-by: Hong Ge <3279477+yebai@users.noreply.github.com> Signed-off-by: Xianda Sun <5433119+sunxd3@users.noreply.github.com>

sunxd3 · 2026-03-30T18:33:01Z

One minor suggestion, to avoid the layers of redirections, can we rename .claude/skills/ir-inspect/SKILL.md to .claude/skills/ir_inspect.md

This is general convention I am afraid

- Clarify forward-mode BBCode is inspection-only in docs and skill - Distinguish LazyDerivedRule vs DynamicDerivedRule (static vs dynamic dispatch) - Fold skill_utils into basic test group, keep standalone selector - Add io kwarg to write_ir

Import set_valid_world! directly instead of qualifying with Mooncake, which is not in scope in submodules on Julia 1.12. Also remove the standalone skill_utils test group since it's already part of basic.

The function is only defined on 1.12+, so importing it unconditionally breaks precompilation on LTS/1.11.

* Respect primitive dispatch in inspect_ir * Format skill_utils helper signature * Relax extract_meta edge-count assertion * format

sunxd3 · 2026-04-04T06:42:31Z

Thanks, @yebai !

sunxd3 added 11 commits March 3, 2026 10:15

Add mooncake-reference skill for conceptual understanding of internals

5deff70

Teaching skill that explains Mooncake's AD pipeline, tangent types, BBCode IR, rule system, and Julia compiler prerequisites. Integrates with ir-inspect to offer live demonstrations of each concept.

Add Julia compiler source URLs for WebFetch reference

d1eef43

Point to raw GitHub URLs for Julia's IRCode, BasicBlock, and AbstractInterpreter source so Claude can fetch them on demand.

Remove Codex-specific references from compiler-rootcause skill

7c066a0

Make the skill tool-agnostic — it now describes reading Julia source via local clone (Grep/Read) or WebFetch, without assuming any particular external AI tool is available.

Remove compiler-rootcause skill

485f77c

update compiler-rootcause skill

bebcbea

Merge remote-tracking branch 'origin/main' into sunxd/cc-skills

75bf1f5

github-actions Bot assigned sunxd3 Mar 5, 2026

yebai mentioned this pull request Mar 16, 2026

Do we need a Claude.md? #1077

Closed

sunxd3 added 9 commits March 23, 2026 05:15

Merge remote-tracking branch 'origin/main' into sunxd/cc-skills

a9b14e8

chore: remove SessionStart hook for Julia installation

b2fd5ac

No longer needed — Claude Code on web now supports setup scripts directly.

chore: remove empty .claude/settings.json

6872a09

Merge remote-tracking branch 'origin/main' into sunxd/cc-skills

045299d

docs: trim advanced_debugging.md and revert Project.toml

49f3a1a

Remove OpaqueClosure/MistyClosure and compiler boundary investigation sections — not actionable debugging guidance. Revert unintended Project.toml formatting changes.

ci: add skill_utils test group and clean up doc blocks

dfddba8

- Add skill_utils to CI matrix (Julia 1.11) - Remove nothing # hide from doc @example blocks

sunxd3 marked this pull request as ready for review March 25, 2026 10:56

Copilot AI review requested due to automatic review settings March 25, 2026 10:56

Copilot started reviewing on behalf of sunxd3 March 25, 2026 10:59 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Comment thread src/skill_utils.jl Outdated

Comment thread src/skill_utils.jl Outdated

Comment thread src/Mooncake.jl

Comment thread src/skill_utils.jl

Comment thread src/skill_utils.jl

Comment thread src/skill_utils.jl Outdated

Comment thread src/skill_utils.jl

style: apply JuliaFormatter to skill_utils

d0fe16d

fix: validate mode kwarg and clarify inspect_ir docstring

eba7f0d

- Throw ArgumentError for invalid mode values instead of silent fallback - Document that world kwarg is diagnostic-only, not used for IR generation - Clarify that optimize/do_inline only affect the final optimization pass

sunxd3 requested review from nsiccha and yebai March 26, 2026 09:22

yebai requested changes Mar 30, 2026

View reviewed changes

yebai and others added 2 commits March 30, 2026 19:29

[codex] Fix IR inspection stage fidelity (#1119)

932ea4f

* Fix IR inspection staging * Fix skill utils world guard

Apply suggestions from code review

db05885

Co-authored-by: Hong Ge <3279477+yebai@users.noreply.github.com> Signed-off-by: Xianda Sun <5433119+sunxd3@users.noreply.github.com>

sunxd3 and others added 5 commits March 30, 2026 19:33

Merge branch 'main' into sunxd/cc-skills

f222653

Fix UndefVarError for Mooncake in SkillUtils on Julia 1.12

ef6c212

Import set_valid_world! directly instead of qualifying with Mooncake, which is not in scope in submodules on Julia 1.12. Also remove the standalone skill_utils test group since it's already part of basic.

Make set_valid_world! import conditional on Julia 1.12+

50d29a6

The function is only defined on 1.12+, so importing it unconditionally breaks precompilation on LTS/1.11.

Respect primitive-rule dispatch in inspect_ir (#1126)

a3576ee

* Respect primitive dispatch in inspect_ir * Format skill_utils helper signature * Relax extract_meta edge-count assertion * format

yebai merged commit 54ee59e into main Apr 3, 2026
139 of 140 checks passed

yebai deleted the sunxd/cc-skills branch April 3, 2026 23:02

yebai mentioned this pull request Apr 3, 2026

coding agent skills for autograd IR transform #1004

Closed


		### Forward mode stages

		`:raw` → `:normalized` → `:bbcode` → `:dual_ir` → `:optimized`

		- `LazyDerivedRule` / `DynamicDerivedRule`: these handle world age
		transitions by recompiling on demand.

Conversation

sunxd3 commented Mar 5, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Summary — GitHub Actions

Documentation Preview

Performance

Uh oh!

github-actions Bot commented Mar 5, 2026

Uh oh!

codecov Bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yebai commented Mar 26, 2026

Uh oh!

yebai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yebai Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

yebai Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

yebai Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sunxd3 commented Mar 30, 2026

Uh oh!

Uh oh!

sunxd3 commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sunxd3 commented Mar 5, 2026 •

edited by github-actions Bot

Loading

codecov Bot commented Mar 5, 2026 •

edited

Loading

github-actions Bot commented Mar 5, 2026 •

edited

Loading