Skip to content

enhancement: Add coding-agent skill library (Claude Code, Copilot, Codex) #1125#1126

Merged
yl-lisen merged 3 commits intodevelopfrom
enhancement/issue-1125-macos-test-runner-and-devex-fixes
Mar 11, 2026
Merged

enhancement: Add coding-agent skill library (Claude Code, Copilot, Codex) #1125#1126
yl-lisen merged 3 commits intodevelopfrom
enhancement/issue-1125-macos-test-runner-and-devex-fixes

Conversation

@yl-lisen
Copy link
Copy Markdown
Collaborator

@yl-lisen yl-lisen commented Mar 10, 2026

Summary

Add a single canonical skill library under .github/skills/ so Claude Code, GitHub Copilot, and Codex all share the same expertise — no duplication.

.github/skills/            ← 10 skills, single source of truth
       ↑                         ↑                    ↑
.claude/skills (symlink)   copilot-instructions.md   .codex/skills (symlink)

Skills: alloc-profile · architecture · build-and-verify · ci-diagnostics · cpp-coding · create-worktree · issue-workflow · review · sql-usage

Also includes minor dev-experience fixes found during macOS local development (macOS test runner, CPython auto-discovery, .gitignore, local helper scripts).

Test plan

  • Claude Code routes tasks via /skill-name
  • tests/ported-clickhouse-test.py runs parallel tests on macOS without fork errors
  • CPython tests skip gracefully when Python 3.10 is absent

Closes #1125

🤖 Generated with Claude Code

@yl-lisen yl-lisen changed the title enhancement: Add coding-agent skill library (Claude Code, Copilot, Codex) #1125 enhancement: Add coding-agent skill library shared across Claude Code, Copilot and Codex #1125 Mar 10, 2026
@yl-lisen yl-lisen force-pushed the enhancement/issue-1125-macos-test-runner-and-devex-fixes branch from 2984fc0 to cda1cd1 Compare March 10, 2026 13:38
@yl-lisen yl-lisen changed the title enhancement: Add coding-agent skill library shared across Claude Code, Copilot and Codex #1125 enhancement: Add coding-agent skill library (Claude Code, Copilot, Codex) #1125 Mar 10, 2026
@yl-lisen yl-lisen requested a review from Copilot March 10, 2026 13:41
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a canonical skill library under .github/skills/ for multiple coding agents, plus local developer-experience improvements (macOS test runner behavior, CPython interpreter discovery, local helper scripts, and ignore patterns).

Changes:

  • Introduce shared agent “skills” docs under .github/skills/ and wire them into Claude/Codex/Copilot instruction entrypoints.
  • Improve local testing on macOS by avoiding fork()-heavy multiprocessing in the SQL test runner.
  • Add local helper scripts (start-local-proton.sh, local_coverage.sh) and related .gitignore entries; improve CPython test setup to skip when Python 3.10 isn’t available.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated no comments.

Show a summary per file
File Description
utils/c++expr Broaden root detection to include Proton and improve error text.
tests/queries_ported/shell_config.sh Make --host stripping regex safer by switching to a raw string.
tests/queries_ported/0_stateless/00534_functions_bad_arguments.lib Use $CLICKHOUSE_CLIENT for function list query generation.
tests/ported-clickhouse-test.py Use threads on macOS to avoid fork-related failures; update Proton naming.
start-local-proton.sh Add local Proton launcher with port auto-selection and log/runtime directory management.
src/CPython/tests/CPythonTest.h Auto-discover Python 3.10 and skip CPython tests when missing.
src/Bootstrap/ServerDescriptor.cpp Switch server port config keys to node.* namespace.
local_coverage.sh Add local LLVM coverage build/test/report workflow script.
base/base/coverage.cpp Silence Clang reserved-identifier warning around __llvm_profile_dump.
AGENTS.md Add agent entrypoint reference.
.gitignore Ignore coverage outputs and local runtime/worktree directories.
.github/skills/sql-usage/references/udf.md Add SQL UDF/UDAF reference doc.
.github/skills/sql-usage/references/stream-types.md Add stream types reference doc.
.github/skills/sql-usage/references/mv-production.md Add production MV configuration reference doc.
.github/skills/sql-usage/references/join-patterns.md Add JOIN patterns reference doc.
.github/skills/sql-usage/references/external-streams.md Add external streams reference doc.
.github/skills/sql-usage/references/emit-policies.md Add EMIT policy reference doc.
.github/skills/sql-usage/SKILL.md Add SQL skill overview and routing rules.
.github/skills/review/SKILL.md Add PR review skill checklist and workflow.
.github/skills/issue-workflow/references/workflow-detail.md Add detailed issue workflow reference.
.github/skills/issue-workflow/SKILL.md Add issue workflow skill overview.
.github/skills/create-worktree/SKILL.md Add worktree creation skill with submodule reuse procedure.
.github/skills/cpp-coding/SKILL.md Add C++ coding conventions and Proton-specific review checklist.
.github/skills/ci-diagnostics/SKILL.md Add CI diagnostics skill and artifact navigation notes.
.github/skills/build-and-verify/references/streaming-verify.md Add streaming verification testing pattern doc.
.github/skills/build-and-verify/references/mv-testing.md Add MV testing pattern doc.
.github/skills/build-and-verify/references/join-testing.md Add JOIN testing pattern doc.
.github/skills/build-and-verify/SKILL.md Add build/test commands and pre-commit checklist.
.github/skills/architecture/references/stream-internals.md Add stream internals architecture reference.
.github/skills/architecture/references/source-layout.md Add source layout overview.
.github/skills/architecture/references/doc-links.md Add primary documentation links.
.github/skills/architecture/references/cluster-deps.md Add cluster dependency hierarchy reference.
.github/skills/architecture/SKILL.md Add architecture skill overview and routing notes.
.github/skills/alloc-profile/scripts/analyze_alloc_profile.py Add script to summarize collapsed allocation profiles.
.github/skills/alloc-profile/SKILL.md Add allocation profiling skill overview.
.github/skills/.gitattributes Add linguist attributes for skill docs.
.github/copilot-instructions.md Point Copilot to the canonical skills and routing table.
.codex/skills Link Codex skills directory to canonical .github/skills.
.codex/config.toml Ensure Codex picks up the .codex/skills path.
.claude/skills Link Claude skills directory to canonical .github/skills.
.claude/CLAUDE.md Add Claude Code instructions and skill routing pointing at canonical skills.
Comments suppressed due to low confidence (6)

tests/ported-clickhouse-test.py:1

  • pool.join() is called after the pool has gone out of scope in the with closing(...) block in the new structure (and, importantly, closing only calls pool.close() on __exit__). As written, pool.join() is also effectively associated with a pool that may not have been properly closed before joining, which can raise ValueError: Pool is still running depending on execution flow. The simplest fix is to move pool.join() back outside the with (like the previous version) so closing closes the pool first, or explicitly call pool.close() before pool.join() while still inside the with.
    tests/ported-clickhouse-test.py:1
  • In the macOS thread-based path, submitted tasks' exceptions will be silently stored in their Futures and never surfaced because the futures are not collected/awaited. This can lead to false-green runs where workers fail early but the main thread never sees the error. Prefer executor.map(...) or store the returned futures and call future.result() (or concurrent.futures.wait(...) + result()) to propagate exceptions.
    src/Bootstrap/ServerDescriptor.cpp:1
  • This change drops support for the legacy keys (tcp.port, tcp_secure.port, http.port, https.port, etc.) that were previously accepted. If existing deployments/configs still use the legacy layout, they will now silently fall back to the defaults (8463/3218/...) and effectively ignore the configured ports. Consider keeping backward-compatible reads (e.g., check node.* first, then fall back to the prior keys) so this isn’t a breaking config change.
    src/CPython/tests/CPythonTest.h:1
  • The buffer returned by Py_DecodeLocale must remain valid for the lifetime of the interpreter (Python expects the program name string to outlive initialization), but it also must be freed (typically with PyMem_RawFree) after Py_Finalize(). The current code sets the program name and then discards the pointer, which causes a leak and makes it impossible to clean up correctly. Store the decoded wchar_t* in a static and free it in TearDownTestSuite() after Py_Finalize(), or avoid Py_DecodeLocale and use a managed lifetime approach consistent with the embedded-Python guidance.
    tests/queries_ported/0_stateless/00534_functions_bad_arguments.lib:1
  • Executing $CLICKHOUSE_CLIENT inside Perl qx{...} runs via a shell command string; if $CLICKHOUSE_CLIENT contains spaces/flags or unexpected characters, this can break the command or become a shell-injection vector in test environments. Prefer invoking a known-safe client binary (as before) or ensure $CLICKHOUSE_CLIENT is a single executable path and pass arguments safely (e.g., by avoiding qx{...} with interpolated shell strings).
    local_coverage.sh:1
  • || true forces _run_unit_tests to always succeed, which makes it impossible for callers to detect unit test failures (even if they try to capture $?). If you want to keep collecting coverage without aborting, capture the exit code into a variable and return it explicitly (or record it for the final summary) instead of unconditionally masking failures.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add .github/skills/ with 10 skills shared by all three agent platforms:
  alloc-profile, architecture, build-and-verify, ci-diagnostics,
  cpp-coding, create-worktree, issue-workflow, review, sql-usage

Each skill has a SKILL.md and optional references/ for deep context.
Entry-points per platform (single source of truth, no duplication):
  .claude/CLAUDE.md + .claude/skills -> .github/skills/   (Claude Code)
  .github/copilot-instructions.md                          (Copilot)
  .codex/config.toml + .codex/skills -> .github/skills/   (Codex)

Also: fix ported-clickhouse-test.py on macOS, CPython auto-discovery,
local_coverage.sh LLVM helper, minor .gitignore and shell fixes.

Co-Authored-By: Claude <[email protected]>
@yl-lisen yl-lisen force-pushed the enhancement/issue-1125-macos-test-runner-and-devex-fixes branch from cda1cd1 to 584b095 Compare March 10, 2026 15:44
@yl-lisen yl-lisen self-assigned this Mar 10, 2026
@yl-lisen yl-lisen requested review from Copilot and yokofly March 10, 2026 15:45
@yl-lisen yl-lisen marked this pull request as ready for review March 10, 2026 15:45
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

tests/queries_ported/0_stateless/00534_functions_bad_arguments.lib:1

  • qx{...} is executed by Perl, so $CLICKHOUSE_CLIENT is interpreted as a Perl scalar (likely empty), not the shell environment variable. This will run an invalid command and can cause the test to fail. Use a literal client binary (as before), or reference the environment explicitly via $ENV{CLICKHOUSE_CLIENT} / $ENV{...} (with appropriate quoting/escaping for spaces).
    tests/ported-clickhouse-test.py:1
  • In non-main threads, signal.signal(...) raises ValueError, which means the os.killpg(...) line is never reached (the exception happens before it). This can prevent stop_tests() from actually terminating the test process group when running under the macOS thread executor. A minimal fix is to only call signal.signal(...) in the main thread (or move os.killpg(...) before those calls), so the process group termination still happens in worker threads.
    src/Bootstrap/ServerDescriptor.cpp:1
  • This removes support for the prior config keys (tcp.port, tcp_secure.port, http.port, https.port, etc.). If existing deployments still use the legacy keys, they will silently fall back to defaults (or ignore configured secure ports), which is a breaking configuration change. Consider supporting both schemas (prefer node.*, fallback to legacy keys) or emitting a clear error/warning when legacy keys are detected.
    src/CPython/tests/CPythonTest.h:1
  • Py_DecodeLocale() allocates memory that should be released with PyMem_RawFree() at teardown (and Python expects the program name buffer to remain valid for the interpreter lifetime). Right now the pointer is not stored anywhere, so it can’t be freed and will leak for the duration of the test process. Store the decoded pointer in a static and free it in TearDownTestSuite() after Py_Finalize().

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>
- Fix gRPC config key in ServerDescriptor to match Server.cpp
- Fix CPython Py_DecodeLocale memory leak with proper lifetime management
- Fix macOS thread safety in stop_tests() by avoiding signal.signal() from worker threads
- Rewrite 00534_functions_bad_arguments.lib from Perl to Bash to fix password @ interpolation bug
- Add graceful skip for 99056 when external MySQL endpoint is unreachable

Co-authored-by: Copilot <[email protected]>
@yl-lisen yl-lisen merged commit ec0dcf6 into develop Mar 11, 2026
9 of 11 checks passed
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.

Add coding-agent skill library shared across Claude Code, Copilot and Codex

3 participants