agentleFS
gnegreiros-uxgnegreiros-ux/agentica-design-system/.claude/skills/codebase-index/SKILL.md

codebase-index

Skill2 starsChanged 45 days agoApache-2.0View on GitHub

Maintain an up-to-date map of Agentica's design system — which components exist, their token dependencies, and where drift is occurring (orphaned/phantom tokens, components without a contract). Use when asked to index the design system, map component dependencies, or check for token drift.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Skill: codebase-index

Reusable capability: index and map the design system. Enables knowing the system's complete state at any time. Type: skill Logical path: .claude/skills/codebase-index/SKILL.md Read before: AGENTS.md, DESIGN.md, governance/rules/tokens-system.md Relations: guidelines/components/, tokens/component.json, .claude/skills/ai-component-metadata/SKILL.md


Objective

Maintain an up-to-date map of the system: which components exist, what their dependencies are, which tokens they consume, and where drift is occurring.


Component index

Generation process

For each component in guidelines/components/:
  1. Read the .md file (contract)
  2. Read the token in tokens/component.json
  3. Identify dependencies (semantic tokens used)
  4. Identify components that use it (consumers)
  5. Compute the completeness score (see ai-component-metadata skill)

Index format

## Component index — [DATE]

| Component | Variants | Tokens | Score | Storybook |
|-----------|-----------|--------|-------|-----------|
| button    | 4         | 18     | 100%  | ✅ |
| input     | 3         | 12     | 70%   | ✅ |
| modal     | 2         | 8      | 40%   | 🟡 |
| badge     | 4         | 6      | 90%   | ✅ |

Relationship graph

Downstream dependencies (component → tokens)

button.primary
  └── semantic.color.action.primary
        └── primitive.color.blue.700
  └── semantic.radius.control
        └── primitive.radius.md
  └── semantic.space.control.padding-x
        └── primitive.space.4

Upstream dependencies (token → components)

semantic.color.action.primary
  ├── component.button.primary
  ├── component.button.secondary (text)
  └── component.input.default (border-focus)

This graph makes it possible to know instantly, if primitive.color.blue.700 is modified, which components are impacted.


Drift detection

Orphaned tokens

Tokens defined in component.json but never used in code.

Phantom tokens

Tokens used in code but not defined in the JSON files.

Components without a contract

Components in the code with no matching .md file in guidelines/.

Detached instances (Figma)

Figma components whose properties have been overridden locally.


System status report

Output format for the Observatory dashboard:

{
  "generatedAt": "2026-05-18T10:00:00Z",
  "components": {
    "total": 12,
    "agentReady": 8,
    "partial": 3,
    "notReady": 1
  },
  "tokens": {
    "primitives": 45,
    "semantic": 38,
    "component": 67,
    "orphaned": 2,
    "phantom": 0
  },
  "accessibility": {
    "violations": 0,
    "warnings": 3
  },
  "drift": {
    "hardcodedValues": 4,
    "deprecatedTokens": 1,
    "detachedInstances": 7
  }
}

Recommended frequency

Index typeFrequencyTrigger
Full indexWeeklyCron or manual
Drift detectionOn every PRCI/CD
Observatory reportDailyCron
Relationship graphOn every token additionCI/CD

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.