# Oxygen Sync > Sync AI documentation with current source code. Use when components, themes, hooks, or exports have been added, modified, or removed in the Oxygen UI package. - Skill: `wso2/oxygen-sync` (Agent Skill) - Install (CLI): `npx skillmds@latest add wso2/oxygen-sync` - Raw SKILL.md: https://api.skillmd.com/api/skills/wso2/oxygen-sync/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: wso2 (https://skillmd.com/u/wso2) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/wso2/oxygen-sync --- # Sync AI Documentation with Source Code ## Purpose Reads the Oxygen UI source code and regenerates all AI documentation files (`.claude/` and `.ai/`) to match the current codebase state. Intended for design system maintainers working inside the `oxygen-ui` repo. ## Rules - **NEVER** modify the root `CLAUDE.md` at the repository root - **NEVER** modify source code files (`src/`) - **NEVER** modify other skill `SKILL.md` files - Preserve existing doc structure, heading hierarchy, and formatting conventions - Use `src/components/index.ts` export order as canonical component ordering - Extract props from actual TypeScript interfaces — never guess or fabricate - Report major additions/removals to the user before writing - Mirror `.claude/` content to `.ai/` after every sync --- ## Phase 1 — Introspect Source Code Read all of the following files to build a complete picture of the current public API: ### Barrel Exports - `packages/oxygen-ui/src/index.ts` - `packages/oxygen-ui/src/components/index.ts` ### Themes - `packages/oxygen-ui/src/styles/Themes/index.ts` - If theme names have changed, read the individual theme files referenced by the index ### Hooks - `packages/oxygen-ui/src/hooks/index.ts` ### Contexts - `packages/oxygen-ui/src/contexts/index.ts` ### Utils - `packages/oxygen-ui/src/utils/index.ts` ### Animations - `packages/oxygen-ui/src/animations/index.ts` ### Compound Components Read the `index.ts` for each compound component directory: - `packages/oxygen-ui/src/components/AppShell/index.ts` - `packages/oxygen-ui/src/components/Header/index.ts` - `packages/oxygen-ui/src/components/Sidebar/index.ts` - `packages/oxygen-ui/src/components/ListingTable/index.ts` - `packages/oxygen-ui/src/components/NotificationPanel/index.ts` - `packages/oxygen-ui/src/components/Form/index.ts` - `packages/oxygen-ui/src/components/Footer/index.ts` - `packages/oxygen-ui/src/components/UserMenu/index.ts` Also check for any **new** component directories under `src/components/` that have their own `index.ts` (e.g., `CodeBlock`, `ColorSchemeImage`, `ColorSchemeToggle`, `ComplexSelect`, `ThemeSwitcher`, `NotificationBanner`, `PageContent`, `StatCard`, `PageTitle`, `SearchBar`, or others). ### Props (as needed) For any component that appears new or changed, read the main `.tsx` file to extract prop interfaces. ### Skills List the directories under `packages/oxygen-ui/.claude/skills/` to capture the current set of available skills. --- ## Phase 2 — Read Current Docs Read all existing documentation files to understand current state and format: - `packages/oxygen-ui/.claude/CLAUDE.md` - `packages/oxygen-ui/.claude/components.md` - `packages/oxygen-ui/.claude/patterns.md` - `packages/oxygen-ui/.claude/theming.md` - `packages/oxygen-ui/.claude/migration.md` --- ## Phase 3 — Report Discrepancies Before writing any files, compile a report of what changed: - **New in source, missing from docs**: Components, hooks, themes, contexts, utils, animations, or type exports found in source but not documented - **In docs, removed from source**: Items documented but no longer exported - **Changed**: Props, sub-components, or type exports that have been modified Present this report to the user and **ask for confirmation** before proceeding with writes. --- ## Phase 4 — Regenerate Documentation After the user confirms, update each file while preserving existing format conventions: ### `.claude/CLAUDE.md` - Update the **Available Themes** list to match `src/styles/Themes/index.ts` - Update the **Custom Oxygen Components** list to match `src/components/index.ts` - Update the **Available Skills** list to match the directories in `.claude/skills/` - Do NOT include `/oxygen-sync` in the Available Skills list (it is internal-only and already listed separately) ### `.claude/components.md` - Update component API tables, props, sub-components, hooks, and type exports - Add entries for new components found in source - Remove entries for components no longer in source - Use `src/components/index.ts` export order for ordering ### `.claude/patterns.md` - Verify all code examples use current APIs (correct component names, prop names, imports) - Update any examples that reference renamed or removed components/props ### `.claude/theming.md` - Update the available themes table - Update theme properties and CSS variables if changed ### `.claude/migration.md` - Verify import examples are accurate - Update any migration guidance affected by API changes ### Mirror to `.ai/` After updating all `.claude/` files, mirror the content to `.ai/`: | Source | Target | Notes | |--------|--------|-------| | `.claude/CLAUDE.md` | `.ai/AGENTS.md` | Adjust paths (`.claude/` -> `.ai/`), remove the Available Skills section | | `.claude/components.md` | `.ai/components.md` | Copy as-is | | `.claude/patterns.md` | `.ai/patterns.md` | Copy as-is | | `.claude/theming.md` | `.ai/theming.md` | Copy as-is | | `.claude/migration.md` | `.ai/migration.md` | Copy as-is | --- ## Phase 5 — Post-Sync Report Summarize what was done: - Files that were **modified** and what changed in each - Files that were **already up to date** (no changes needed) - Any items that need manual attention (e.g., complex prop changes that need human review)