codebase-index
Generate a pre-computed component index from a design system codebase — YAML infrastructure files containing a component inventory, relationship graph, and summary statistics that AI agents and MCP servers consume. This produces machine-readable index files in .ai/index/, NOT a health report or quality assessment. Trigger when someone says: index my codebase, build a relationship graph, create a component map, codebase index, what depends on what, dependency graph, map component relationships, or anything about producing queryable infrastructure files for AI agents or developer tooling. Do NOT trigger for component health assessments, quality scores, or audit reports — use component-audit for those.
murphytrueman · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add murphytrueman/design-system-ops --skill codebase-index技能说明
name: codebase-index description: "Generate a pre-computed component index from a design system codebase — YAML infrastructure files containing a component inventory, relationship graph, and summary statistics that AI agents and MCP servers consume. This produces machine-readable index files in .ai/index/, NOT a health report or quality assessment. Trigger when someone says: index my codebase, build a relationship graph, create a component map, codebase index, what depends on what, dependency graph, map component relationships, or anything about producing queryable infrastructure files for AI agents or developer tooling. Do NOT trigger for component health assessments, quality scores, or audit reports — use component-audit for those." references:
- ../../knowledge-notes/ai-readiness.md
- ../../knowledge-notes/component-governance.md
Codebase index
A skill for generating a pre-computed, machine-readable index of a design system's codebase. The index contains three pieces: a component inventory, a relationship graph, and summary statistics. Together they form a queryable map that eliminates the need for AI agents or developers to explore the codebase from scratch every time they need to understand the system.
Context
When an AI agent needs to work with a design system codebase, it has two options: explore or navigate. Exploration means scanning directories, grepping for imports, reading files one by one. Navigation means loading a pre-computed index and reasoning over cached data.
The difference matters. Exploration is slow, incomplete, and non-deterministic. An agent scanning src/components might miss components in src/layouts, src/pages, or utility directories that don't follow naming conventions. It might report a deeply-nested component as "unused" because it can't trace the dependency chain. It might recreate an existing component because it didn't find it.
A pre-computed index front-loads this cost. The agent loads the index once — typically a few thousand tokens — and gets a complete picture of what exists, where things live, and how they relate. Follow-up questions become cheap because the agent reasons over cached data instead of triggering new file reads.
This skill generates that index. Run it after adding or removing components, and commit the output alongside the code.
Configuration
Before producing output, check for a .ds-ops-config.yml file in the project root. If present, load:
system.framework— pre-selects framework detection (React, Vue, Svelte, Astro, Angular, etc.)system.component_paths— overrides default component directory scanningsystem.category_model— atomic design, functional, or custom categorisationintegrations.*— enables auto-pull for component datarecurring.*— enables comparison with previous index
Auto-pull integrations
If integrations are configured in .ds-ops-config.yml, pull data automatically:
Figma MCP (integrations.figma.enabled: true):
- Read the published library from
integrations.figma.file_key - Cross-reference the Figma component inventory against the code inventory to detect components that exist in design but not in code (or vice versa)
- Pull description status per component to populate the metadata coverage field
Storybook (integrations.storybook.enabled: true):
- Fetch the story index from
integrations.storybook.url/index.json - Extract component list and documentation status
- Use as a secondary source for component discovery
GitHub (integrations.github.enabled: true):
- Use
gh api search/codeto count import references across consuming repositories - Pull PR activity for recency signals
If an integration fails, log it and proceed with manual scanning.
Step 1: Detect the framework and structure
Scan the project root to determine:
- Framework: React (JSX/TSX), Vue (SFC), Svelte, Astro, Angular, Web Components, or mixed
- Component directories: Where components live — scan common locations:
src/components/,src/lib/,components/,packages/, and any paths intsconfig.jsonor framework config - Category model: How components are organised — atomic design (
atoms/,molecules/,organisms/), functional (forms/,navigation/,feedback/), flat, or monorepo packages - Styling approach: CSS modules, CSS-in-JS, Tailwind, SCSS, or design tokens — this determines how to trace token dependencies
Ask for or confirm (skip questions already answered by config or detection):
- The component source root if auto-detection finds multiple candidates
- Whether there are components in non-standard locations (e.g., a shared
utils/directory with reusable UI primitives) - Whether to include internal/private components in the index (underscore-prefixed,
internal/directories, components not re-exported from barrel files)
Framework detection rules:
| Signal | Framework |
|---|---|
.jsx / .tsx files with JSX returns | React |
.vue files with <template> blocks | Vue |
.svelte files | Svelte |
.astro files | Astro |
.component.ts with @Component decorator | Angular |
customElements.define() | Web Components |
| Mixed signals | Ask the user |
Step 2: Scan and build the component inventory
For every component file found, extract:
- Name: The component's exported name
- Path: Relative path from project root
- Category: Based on the category model (atom, molecule, organism, etc.) or functional category (navigation, form, feedback, layout, data display)
- Metadata status: Whether the component has structured metadata (a
.metadata.ts,.metadata.json, description in Storybook, JSDoc/TSDoc block, or Figma description) - Export type: Default export, named export, or re-exported through a barrel file
What counts as a component:
- Files that export a renderable element (JSX, template, render function)
- Files explicitly registered in a component index, barrel fi