extract-to-lib
Skill501 starsChanged 17 days agoApache-2.0View on GitHub
Move reusable code from apps/* into a lib (usually libs/chat-hooks) without changing any entry point's peer set, losing tests, or leaving docs and specs pointing at the old path. Finds app enums, types, constants and helpers that duplicate or should live in a lib, checks whether a design doc keeps them host-owned, picks the module and entry point, moves code and tests, rewires imports, and updates README, specs and docs. Use when asked to move, extract or share app code with another host, to deduplicate an app type against a lib, or when `npm run validate:lib-duplicates` fails.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/a11y.mdcCursor rule
- nx-generateSkill
- nx-importSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- address-current-branch-reviewSkill
- api-designSkill
- celebration-scene-ideasSkill
- code-review-and-qualitySkill
- create-ticketSkill
- dep-scanSkill
- dep-triageSkill
- dial-docsSkill
- figmaSkill
- fix-cve-backportSkill
- git-shipSkill
- i18n-stringsSkill
- lean-verificationSkill
- lib-themingSkill
- monitor-ciSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- proactive-security-monitorSkill
- refactoring-auditSkill
- chat-release-notesSkill
- responsive-designSkill
- security-monitor-triagerSkill
- snyk-jira-ingestSkill
- snyk-scan-stubSkill
- snyk-triageSkill
- ui-kit-reviewSkill
- nx-generateSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- nx-generateSkill
- nx-importSkill
- nx-pluginsSkill
- nx-run-tasksSkill
- nx-workspaceSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Before moving, search docs/ and openspec/specs/ for the function name and its file path.
- Distinctive: line 38
Only the parts the doc calls shared move.
- Very specific: line 42
Put the code next to its domain in the lib (scheduled-task/, catalog/, conversation-sources/, shared/), one file per concept, kebab-case.
- Very specific: line 49
Import other modules of the same lib by relative path (../shared/string-utils), never through the lib's own package name.
- Distinctive: line 70
When the lib returns a lib enum, keep the app's own copy-mapping in the app (e.g.
- Very specific: line 72
Every exported symbol and every interface field gets a JSDoc (.claude/rules/libs.md).
- Distinctive: line 79
Delete the app file once nothing imports it.
- Distinctive: line 83
Add a README section per new export: what it returns, where it is available (root and subpath), a minimal example that compiles.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Extract to lib
An app keeps what only it knows — routes, i18n, storage keys, app contexts,
server-api, feature flags. Everything else that another host would need as-is
belongs in a lib, reached through a public export. This skill moves it there
without widening what a host must install.
1. Find candidates
npm run validate:lib-duplicateslists app enums that re-declare a lib enum.- For a folder (
apps/chat/src/utils,types,models), tag each file by what it imports:i18next/translation-keys,server-api//api/, routes, storage, app contexts. A file with none of these is a candidate. - Grep each candidate's exported names under
libs/*/src. A same-shaped type or same-valued enum already exported by a lib is a duplicate: delete the app copy and import the lib's — nothing moves. - A comment saying a value "mirrors" or is "kept in sync" with a lib is a private lib value that should be exported.
- For
apps/chat/src/components, the same import test finds presentational components: one that reads no app context, router,t()orserver-api— often already taking every string as a prop — belongs in the feature lib it renders, orlibs/chat-shared.npm run validate:lib-duplicatesprints these as warnings. - A block repeated verbatim in two app components is an app utility even when
it uses
t(); dedupe it inside the app.
2. Check it is not host policy
Before moving, search docs/ and openspec/specs/ for the function name and
its file path. A doc that records a rule as host-owned (an id parser, an
ownership or routing decision, notification copy) wins: leave it in the app,
even when two hosts' copies look alike — they may parse different id formats.
Only the parts the doc calls shared move.
3. Pick the module and the entry point
- Put the code next to its domain in the lib (
scheduled-task/,catalog/,conversation-sources/,shared/), one file per concept, kebab-case. - Export it from the root
index.tsand the subpath entry insrc/entry-points/whose peers already cover every package the code imports. Read the lib README's entry-point-to-peer matrix: a new import must not add a peer to any entry point. If no entry fits, keep the code out of that entry rather than widening it. - Import other modules of the same lib by relative path (
../shared/string-utils), never through the lib's own package name. libs/chat-hooksstays non-rendering and host-agnostic (seeAGENTS.md"Library isolation"): pass translated labels, locale, URLs and id comparison in as parameters.- A component goes to a feature lib or
libs/chat-shared, never tolibs/chat-hooks. It follows.claude/rules/libs.md:*Labelswith English defaults copied fromen.json, colours through*Colorsand CSS variables, typography through*ClassNameprops. The app component that stays becomes a thin adapter passing translated copy and state. - A component in a lib that
chat-hookscannot import (every lib except the onesAGENTS.mdlists) cannot take achat-hooksenum as a prop. Give it plain props (isVisible,isLoggingIn,retryMessage) and keep the enum-to-props mapping in the app adapter.
4. Move code and tests together
git mvthe file when it moves whole, so history follows; otherwise cut the block and keep the app file for what stays.- Move the matching
describeblocks intotests/beside the new module. Replace app-only test helpers with a small local stand-in. - When the lib returns a lib enum, keep the app's own copy-mapping in the app (e.g. lib kind → app notification noun) instead of moving the app enum.
- Every exported symbol and every interface field gets a JSDoc (
.claude/rules/libs.md).
5. Rewire the app
- Merge the new names into the file's existing import from the lib; do not add a second import from the same module.
- Drop casts that only bridged the old app type to the lib type.
- Delete the app file once nothing imports it; grep the old path.
6. Docs and specs, same change
- Add a README section per new export: what it returns, where it is available (root and subpath), a minimal example that compiles.
- Fix every
openspec/specs/**anddocs/**reference to the old path or name. - Run
npm run validate:docs,npm run validate:specs,npm run validate:lib-duplicates, thennx run-many -t lint typecheckfor the lib and the app. In a git worktree, follow "Verifying in a git worktree" in thelean-verificationskill first — otherwise Nx checks the main checkout instead of the change.
7. Traps
Each of these broke or nearly broke a move:
- Object-literal test mocks. An app spec that mocks a lib with
vi.mock('@epam/…', () => ({ … }))hides every export it does not list — including the component or enum the app now imports from that lib, and anything another lib reads from it. Grepapps/**/*.spec.tsxfor such mocks of the target lib and add the new export withimportOriginal. - Module-level reads of another lib. A lib module that reads another lib's
enum at import time (a
Recordkeyed by it, aSetof its members) crashes every test that mocks that lib without the enum. Keep such maps inside the function, or keep the enum in the same lib as the code that reads it. - Hidden peers. A relative import can pull a module whose own imports add a
peer to the entry point (
usage/usage-banner-source.tsimports@epam/ai-dial-conversation-input). Move the shared piece to a dependency-free module and re-export it from the old one. - New runtime imports in a lib.
createPortalneedsreact-domas a peer; check the lib'spackage.jsonbefore using a package it does not declare, add it in the same change, runnpm run docs:install-matrix, and update the README peer list. - App tests of moved code. Move or delete the app spec for the function, or
nx typecheckfails on an import the app module no longer exports. - Router internals are routing. A helper with no router import can still
depend on the router: reading react-router's
history.state.usris router knowledge and stays in the app, while a pure query-string rewrite ofwindow.locationcan move. Split such a file instead of moving it whole (getCurrentRouterStatestayed,getCleanedLocationTargetmoved). - A label the kit ignores. A kit
Button(andGhostButton,PrimaryButton, …) with a stringlabelnames itself from that label and dropsaria-label. Do not carry an app'saria-labelfor such a button into a lib*Labelsfield: nothing would read it. Check the rendered accessible name, not the prop list. - Docs that say "keep in the app". A guide that keeps a callback in the host may still allow the callback to call a lib helper; update the guide to name it rather than moving the callback.
8. Report
List what moved (name, module, entry points), what was deleted as a duplicate, and what stayed host-owned and why. Note any behaviour difference a host gets by adopting the lib version instead of its own.
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
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.

