chore: add claude code skills and subagent configuration#912
chore: add claude code skills and subagent configuration#912Patrick Nilan (pnilan) wants to merge 3 commits intomainfrom
Conversation
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksTesting This CDK VersionYou can test this version of the CDK using the following: # Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@pnilan/claude/add-skills-subagents#egg=airbyte-python-cdk[dev]' --help
# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch pnilan/claude/add-skills-subagentsPR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
|
|
test -- closing |
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughThis PR adds documentation for new Claude agents and skills designed to research and assist with the Airbyte Python CDK codebase. Four agents are documented for exploring code components, schema layers, and connectors. Four skills provide workflows for creating pull requests, generating diagrams, explaining code, and writing PR descriptions. A minor .gitignore update adds a notes exclusion rule. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. 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 |
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive set of Claude Code skills and subagent configurations to the airbyte-python-cdk repository. The skills automate common development workflows like generating PR descriptions, creating pull requests with conventional commit titles, explaining CDK architecture, and generating flow diagrams. Three specialized subagents (connector-researcher, cdk-schema-researcher, cdk-code-researcher) support these skills by fetching and analyzing code from both the local CDK and the remote Airbyte monorepo.
Changes:
- Added 4 new Claude Code skills for PR management, code explanation, and diagram generation
- Added 3 subagent configurations for researching connectors, schemas, and CDK code
- Updated .gitignore to exclude the
/thoughtsdirectory where generated documentation is saved
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
.gitignore |
Adds /thoughts directory to ignore list for generated documentation |
.claude/skills/generate-pr-description/SKILL.md |
Defines skill for generating PR descriptions by analyzing git diffs |
.claude/skills/explain/SKILL.md |
Defines skill for explaining Python CDK structure and components with fast/full modes |
.claude/skills/diagram/SKILL.md |
Defines skill for generating Mermaid flowcharts and sequence diagrams |
.claude/skills/create-pr/SKILL.md |
Defines skill for creating GitHub PRs with conventional commit titles and auto-generated descriptions |
.claude/agents/connector-researcher.md |
Defines subagent for fetching connector code from Airbyte monorepo via GitHub API |
.claude/agents/cdk-schema-researcher.md |
Defines subagent for tracing YAML component definitions to Python implementations |
.claude/agents/cdk-code-researcher.md |
Defines subagent for exploring local CDK codebase and explaining components |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - <bullet point list of key changes> | ||
|
|
||
| ## Recommended Review Order | ||
| <ordered list of recommended review order. only include files with significant changes. avoid including tests, changelogs, documentation, and other files with trivial cahnges> |
There was a problem hiding this comment.
Spelling error: "cahnges" should be "changes".
| <ordered list of recommended review order. only include files with significant changes. avoid including tests, changelogs, documentation, and other files with trivial cahnges> | |
| <ordered list of recommended review order. only include files with significant changes. avoid including tests, changelogs, documentation, and other files with trivial changes> |
| --- | ||
| description: Creates a GitHub pull request with a generated description by analyzing the current branch diff against main. Use when the user wants to open a PR. | ||
| user_args: "[--title '<type>: description']" |
There was a problem hiding this comment.
The PR description states "Enhances the Claude Code /create-pr skill" and "Updated the SKILL.md for the create-pr skill", implying this is an update to an existing file. However, this PR actually creates 4 brand new skill files (generate-pr-description, explain, diagram, create-pr) and 3 new agent configuration files (connector-researcher, cdk-schema-researcher, cdk-code-researcher). The PR description should be updated to accurately reflect that this is adding entirely new skills and agent configurations, not just enhancing an existing create-pr skill.
| 2. **Use sub-agents to trace the flow:** | ||
| ``` | ||
| Task(subagent_type="codebase-analyzer", prompt="Trace the data flow for [component/concept] in the Airbyte Python CDK. | ||
| Identify: entry points, class hierarchies, method call chains, data transformations, and exit points. | ||
| Focus on the runtime behavior — how data actually flows through the code. | ||
| Document with file:line references.") | ||
| ``` | ||
|
|
||
| 3. **Read the relevant source files** to understand: | ||
| - Entry points (where does execution start?) | ||
| - Class hierarchies (what extends what?) | ||
| - Method call chains (what calls what in sequence?) | ||
| - Data transformations (how is data shaped along the way?) | ||
| - Branching logic (where do different code paths diverge?) | ||
| - Integration points (where does this connect to other CDK subsystems?) | ||
|
|
||
| #### Change Mode | ||
|
|
||
| 1. **Get the commit history:** | ||
| ```bash | ||
| git log main..HEAD --oneline | ||
| ``` | ||
|
|
||
| 2. **Get the full diff:** | ||
| ```bash | ||
| git diff main...HEAD | ||
| ``` | ||
|
|
||
| 3. **List changed files:** | ||
| ```bash | ||
| git diff main...HEAD --name-only | ||
| ``` | ||
|
|
||
| 4. **Use sub-agents to understand impacted flows:** |
There was a problem hiding this comment.
Inconsistent terminology: The document uses "sub-agents" on line 76 and line 109, but uses "subagents" on lines 78 and 111 (in the code examples with subagent_type parameter). Additionally, the explain skill uses "subagents" (line 21 in explain/SKILL.md). Consider standardizing to one form throughout all skill documentation. "subagent_type" in code examples suggests the unhyphenated form may be preferred.
| For example (assuming today is 2025-06-15): | ||
| - `thoughts/explanations/2025-06-15-pagination-types.md` | ||
| - `thoughts/explanations/2025-06-15-source-harvest-pagination.md` | ||
| - `thoughts/explanations/2025-06-15-low-code-runtime.md` |
There was a problem hiding this comment.
The example date "2025-06-15" is in the past (current date is February 19, 2026). While this is clearly marked as an example with "(assuming today is 2025-06-15)", consider updating to a more recent example date or using a generic placeholder like "(assuming today is 2026-02-19)" to avoid confusion.
| For example (assuming today is 2025-06-15): | |
| - `thoughts/explanations/2025-06-15-pagination-types.md` | |
| - `thoughts/explanations/2025-06-15-source-harvest-pagination.md` | |
| - `thoughts/explanations/2025-06-15-low-code-runtime.md` | |
| For example (assuming today is 2026-02-19): | |
| - `thoughts/explanations/2026-02-19-pagination-types.md` | |
| - `thoughts/explanations/2026-02-19-source-harvest-pagination.md` | |
| - `thoughts/explanations/2026-02-19-low-code-runtime.md` |
What
Enhances the Claude Code
/create-prskill to use semantic/conventional commit PR title conventions and support an optional--titleflag for user-provided titles.How
Updated the
SKILL.mdfor the create-pr skill to replace the generic title generation instructions with a full conventional commits specification, including allowed types (feat,fix,docs,refactor, etc.), optional scope syntax, and breaking change notation. Added auser_argsfrontmatter field so users can pass--titleto override the generated title.Changes
user_argsfrontmatter field to support--titleflag in create-pr skill--titleis passed, otherwise auto-generateRecommended Review Order
.claude/skills/create-pr/SKILL.mdSummary by CodeRabbit
Release Notes
No user-facing changes. This release includes internal documentation updates for development workflows and infrastructure tooling. Added comprehensive guides for code research, analysis, and pull request generation processes.