Split skills-map.mjs into a validated source registry

[tonyblu331]

This is a revised take on my first PR, #31 .

Right now autoskills grows through one shared file: skills-map.mjs.

That means unrelated contributions end up competing on the same authoring surface. As support grows, the file becomes harder to review, easier to conflict on, and easier to accidentally overwrite during rebases or manual conflict resolution.

The issue is not the runtime contract itself. The issue is that the runtime artifact is also the main authoring surface.

Before

contributor
  -> edits skills-map.mjs directly
  -> touches shared global map
  -> broad diff / merge pressure
  -> runtime consumes the same file

Before API

import {
  SKILLS_MAP,
  COMBO_SKILLS_MAP,
  FRONTEND_PACKAGES,
  FRONTEND_BONUS_SKILLS,
  WEB_FRONTEND_EXTENSIONS,
  AGENT_FOLDER_MAP,
} from './skills-map.mjs'

Before repo shape

packages/autoskills/
  skills-map.mjs
  lib.mjs
  index.mjs

Describe the solution you'd like

Split authoring for technologies and combos into small source records, then build the existing skills-map.mjs from those records.

The runtime stays the same. lib.mjs can keep consuming skills-map.mjs exactly as it does today.

After DX

Add support for python
  -> add registry/technologies/python.mjs
  -> validate registry
  -> build skills-map.mjs
  -> commit one local record + generated output
  -> narrower review surface

After API

import {
  SKILLS_MAP,
  COMBO_SKILLS_MAP,
  FRONTEND_PACKAGES,
  FRONTEND_BONUS_SKILLS,
  WEB_FRONTEND_EXTENSIONS,
  AGENT_FOLDER_MAP,
} from './skills-map.mjs'

No runtime API change. The proposal only changes how skills-map.mjs is authored and validated.

After repo shape

packages/autoskills/
  registry/
    technologies/
    combos/
    frontend/
    agents/
  scripts/
    validate-registry.mjs
    build-skills-map.mjs
  skills-map.mjs
  lib.mjs
  index.mjs

Describe alternatives you've considered

The first alternative was my original PR, #31 , which introduced an indexed runtime registry. I still think the direction was valid, but the feedback was fair: it added more runtime abstraction than needed for the problem at hand.

Another alternative is to keep the current monolithic skills-map.mjs and continue adding support directly there. That is the simplest option short term, but it keeps the same shared-write hotspot and does not improve contribution DX as the catalog grows.

This revised proposal tries to keep the good part of the original idea, separating authoring from runtime concerns, while staying much more pragmatic and keeping the runtime contract unchanged.

If approved, I’ll work on this.

[tonyblu331]

Se me puede responder en español, hice la issue en inglés por motivos de que cualquier otra persona lo pueda entender.

[d0whc3r]

Si junto con esta, se hace el cambio a TypeScript entonces estaría perfecto.
#67

[isonnymichael]

Yeah, it's hard to maintain when everything is handled in a single file. Currently, all logic is centralized in skills-map.mjs, so making it more modular would significantly improve maintainability.

[midudev]

Thanks for the well-thought-out proposal — the problem you're describing (shared-write hotspot, merge pressure) is real and will definitely matter as the catalog grows.

That said, after reviewing the current state of the project, I think we're not at that point yet:

• skills-map is ~1,300 lines of purely declarative data — no logic, no abstractions. It's a flat list of objects with id, name, detect, and skills. That's very manageable to read and review.
• Merge conflicts on declarative arrays are trivial to resolve. They're almost always "add block at end of array" — git often auto-resolves them, and when it doesn't, the fix is mechanical.
• The build step adds real friction for contributors. Today: add your block, run tests, done. With the registry: create file in the right directory, run validation, run build, verify generated output, commit source + artifact. That's a higher bar for a first-time contributor adding a single technology.
• The generated artifact still gets committed, so PR diffs don't get smaller — they get larger (source file + generated output).
• Validation doesn't require a split. A test that walks SKILLS_MAP and checks each entry's structure (required fields, ID format, valid skill paths, etc.) achieves the same safety net without changing the architecture.

I'd suggest a more pragmatic path for now:

1. A schema validation test that ensures every entry in SKILLS_MAP and COMBO_SKILLS_MAP has the correct structure.
2. A contributing guide with a clear template for adding a new technology.
3. Revisit the split when it actually hurts — e.g., when we hit 300+ technologies or start seeing frequent merge conflicts in practice.

The direction is valid — separating authoring from runtime is a good instinct. I just think the complexity cost outweighs the benefit at the current scale. When the catalog grows enough to justify it, this proposal will be a great reference.