feat(skills): add codebase-onboarding skill#553
Merged
affaan-m merged 8 commits intoaffaan-m:mainfrom Mar 20, 2026
Merged
Conversation
Contributor
|
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:
📝 WalkthroughWalkthroughAdds a new "Codebase Onboarding" skill: documentation in two locations and an OpenAI agent config enabling implicit invocation. No executable code or public API/signature changes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 |
Contributor
Greptile SummaryThis PR adds a new Remaining issues:
Confidence Score: 3/5
Important Files Changed
Sequence DiagramsequenceDiagram
actor User
participant Skill as codebase-onboarding
participant Glob as Glob/Grep Tools
participant FS as File System
participant Output as Output Files
User->>Skill: "Onboard me to this codebase"
Skill->>Glob: Phase 1 — Parallel Reconnaissance
Glob->>FS: Detect package manifests
Glob->>FS: Fingerprint frameworks
Glob->>FS: Find entry points
Glob->>FS: Snapshot directory tree
Glob->>FS: Detect config & tooling
Glob->>FS: Find test structure
FS-->>Skill: Raw signals
Skill->>Skill: Phase 2 — Architecture Mapping
Note over Skill: Identify tech stack, pattern,<br/>key directories, data flow
Skill->>Skill: Phase 3 — Convention Detection
Note over Skill: Naming, error handling,<br/>async patterns, git conventions
Skill->>Output: Phase 4 — Generate Artifacts
Output->>User: Onboarding Guide (conversation / project root)
Output->>FS: CLAUDE.md (project root, create or enhance)
Last reviewed commit: "fix: add shallow-clo..." |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/codebase-onboarding/SKILL.md:
- Around line 11-50: The SKILL.md uses "Onboarding Workflow" and lacks explicit
"How It Works" and "Examples" sections required by the skill-format template;
rename the "Onboarding Workflow" heading to "How It Works", move the Phase 1–4
bullets under that heading, and add a new "Examples" section containing 2–3
concise examples showing (a) activation triggers (e.g., "User: onboard me" or
first open) and (b) expected outputs (e.g., "Onboarding Guide" and "Starter
CLAUDE.md"); ensure headings match the repo template and keep the existing "Best
Practices" content intact.
In `@skills/codebase-onboarding/SKILL.md`:
- Around line 11-210: The SKILL.md uses nonstandard headings (e.g., "When to
Activate", "Onboarding Workflow", "Phase 1…4", "Output 1/2") but must follow the
required schema "When to Use", "How It Works", and include an explicit
"Examples" section; update the document headings by renaming or aliasing "When
to Activate" -> "When to Use", consolidate "Onboarding Workflow" and the Phase
1–4 descriptions under a "How It Works" heading (keep phase bullets as
subsections), and add a clear "Examples" section showing sample Reconnaissance
checks and a sample generated CLAUDE.md (use the existing Output 1/Output 2
content as examples); ensure the top-level headings "When to Use", "How It
Works", and "Examples" appear in SKILL.md.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 472bb8a2-bd46-4ed2-b6a8-7c74c119f445
📒 Files selected for processing (3)
.agents/skills/codebase-onboarding/SKILL.md.agents/skills/codebase-onboarding/agents/openai.yamlskills/codebase-onboarding/SKILL.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 3 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="skills/codebase-onboarding/SKILL.md">
<violation number="1" location="skills/codebase-onboarding/SKILL.md:166">
P2: Workflow contradiction: it says to enhance existing CLAUDE.md, but Output 2 only instructs generating a new file and never requires reading/merging an existing one.</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Add one-off context when rerunning by tagging
@cubic-dev-aiwith guidance or docs links (includingllms.txt) - Ask questions if you need clarification on any suggestion
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
2 issues found across 2 files (changes from recent commits).
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/codebase-onboarding/SKILL.md">
<violation number="1" location=".agents/skills/codebase-onboarding/SKILL.md:79">
P2: The onboarding workflow is overly HTTP-centric: it requires tracing a request/response lifecycle and a `Request Lifecycle` section even for non-service repos, risking inaccurate generated docs.</violation>
<violation number="2" location=".agents/skills/codebase-onboarding/SKILL.md:149">
P2: Onboarding guide template hardcodes Node/Prisma commands despite claiming multi-ecosystem support, which can produce incorrect setup instructions for non-Node repositories.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.agents/skills/codebase-onboarding/SKILL.md (1)
222-223: Consider softening the fixed output path in examples.The example currently implies mandatory write locations. Consider wording it as “for example” to avoid over-constraining implementations across harnesses/repos.
✏️ Suggested wording tweak
-**Output**: Two artifacts written to `docs/onboarding-guide.md` and `CLAUDE.md` +**Output**: Two artifacts (for example, `docs/onboarding-guide.md` and `CLAUDE.md`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/codebase-onboarding/SKILL.md around lines 222 - 223, Update the Output wording in .agents/skills/codebase-onboarding/SKILL.md so it doesn't assert fixed write locations; replace the current line "**Output**: Two artifacts written to `docs/onboarding-guide.md` and `CLAUDE.md`" with a softened variant such as "**Output (example)**: Two artifacts, e.g. written to `docs/onboarding-guide.md` and `CLAUDE.md`" or "**Output**: Two artifacts (for example: `docs/onboarding-guide.md` and `CLAUDE.md`)" to indicate these paths are illustrative rather than mandatory.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.agents/skills/codebase-onboarding/SKILL.md:
- Around line 222-223: Update the Output wording in
.agents/skills/codebase-onboarding/SKILL.md so it doesn't assert fixed write
locations; replace the current line "**Output**: Two artifacts written to
`docs/onboarding-guide.md` and `CLAUDE.md`" with a softened variant such as
"**Output (example)**: Two artifacts, e.g. written to `docs/onboarding-guide.md`
and `CLAUDE.md`" or "**Output**: Two artifacts (for example:
`docs/onboarding-guide.md` and `CLAUDE.md`)" to indicate these paths are
illustrative rather than mandatory.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4654230e-7dad-4d6c-9d8e-c62aa3db134f
📒 Files selected for processing (3)
.agents/skills/codebase-onboarding/SKILL.md.agents/skills/codebase-onboarding/agents/openai.yamlskills/codebase-onboarding/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (2)
- skills/codebase-onboarding/SKILL.md
- .agents/skills/codebase-onboarding/agents/openai.yaml
Contributor
Author
|
@affaan-m Ready for review — all bot feedback has been addressed. |
Owner
|
Thanks for the codebase-onboarding skill! This fills a real gap. Items to address:
|
Adds a skill that systematically analyzes an unfamiliar codebase and produces two artifacts: a structured onboarding guide and a starter CLAUDE.md tailored to the project's conventions. Four-phase workflow: 1. Reconnaissance — parallel detection of manifests, frameworks, entry points, directory structure, tooling, and test setup 2. Architecture mapping — tech stack, patterns, key directories, request lifecycle tracing 3. Convention detection — naming, error handling, async patterns, git workflow from recent history 4. Artifact generation — scannable onboarding guide + project-specific CLAUDE.md Includes Antigravity support via .agents/skills/ and openai.yaml.
- Rename headings to match skill format: When to Activate → When to Use, Onboarding Workflow → How It Works - Add Examples section with 3 usage scenarios - Mark Phase 4 Next.js paths as example with HTML comments - Fix CLAUDE.md generation to read/enhance existing file first - Replace abbreviated .agents/ SKILL.md with full copy per repo convention
Adds <!-- Example for a Node.js project --> comment to Common Tasks, matching the markers already on Key Entry Points and Where to Look. Syncs .agents/ copy.
- Add example comment to Tech Stack table in Phase 4 template - Add example comment to Key Directories block in Phase 2 - Shorten openai.yaml default_prompt to match repo convention (~60 chars) - Sync .agents/ SKILL.md copy
- Phase 3: add fallback for repos with no git history - Example 1: remove hardcoded docs/ path assumption, output to conversation or project root instead - Sync .agents/ copy
vazidmansuri005
force-pushed
the
feat/codebase-onboarding-skill
branch
from
5104af5 to
03821dc
Compare
Contributor
Author
|
Done — removed the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
codebase-onboardingskill that analyzes unfamiliar codebases and generates structured onboarding guides + starter CLAUDE.md filesskills/codebase-onboarding/SKILL.mdMotivation
Every developer joining a new project faces the same ramp-up friction. This skill turns "help me understand this codebase" into a systematic 4-phase workflow that produces two actionable artifacts in under 2 minutes.
What It Does
Key Design Decisions
Type
Checklist