@joktec/skills 0.1.2 → 0.1.4

package/README.md

@@ -109,19 +109,28 @@ The result is less prompt repetition, better package boundary discipline, and mo
 
 `joktec-framework-skill` is the required entrypoint skill. Installers should always include it so agents can route from a generic JokTec request to the correct focused skill.
 
-`joktec-common-skill` is the default foundation skill. Focused package skills such as Mongo, MySQL, brokers, adapters, integrations, and tools depend on the entrypoint and recommend the common skill because most package usage flows rely on core config, lifecycle, or base abstractions.
+`joktec-common-skill` is the required foundation skill. It depends on `joktec-framework-skill`. Focused package skills such as Mongo, MySQL, brokers, adapters, integrations, and tools depend on both `joktec-framework-skill` and `joktec-common-skill` because most package usage flows rely on core config, lifecycle, or base abstractions.
 
 Dependency metadata lives in `skill-pack.json`:
 
 ```json
 {
   "id": "joktec-mongo-skill",
-  "dependencies": ["joktec-framework-skill"],
-  "recommended": ["joktec-common-skill"]
+  "dependencies": ["joktec-framework-skill", "joktec-common-skill"],
+  "recommended": []
 }
 ```
 
-The CLI resolves `dependencies` automatically. `recommended` skills are shown to the user and can be installed with `--yes` or explicit selection.
+The `@joktec/skills` CLI resolves `dependencies` automatically.
+
+The ecosystem `npx skills` CLI currently installs exactly the skills selected in its prompt. When using it, select dependencies manually or pass them explicitly:
+
+```bash
+npx skills add joktec/joktec-skills -a codex --project . \
+  --skill joktec-framework-skill joktec-common-skill joktec-mongo-skill
+```
+
+`npx skills` also writes a project-level `skills-lock.json`. Keep that file if the project wants reproducible skill updates or restore support through the ecosystem CLI.
 
 ---
 
@@ -197,6 +206,13 @@ Install focused skills. Required dependencies are included automatically:
 npx @joktec/skills add mongo,mysql --agent codex --project .
 ```
 
+Using the ecosystem `skills` CLI:
+
+```bash
+npx skills add joktec/joktec-skills -a codex --project . \
+  --skill joktec-framework-skill joktec-common-skill joktec-mongo-skill
+```
+
 Install for multiple agents:
 
 ```bash

package/bin/joktec-skills.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import readlinePromises from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { DIST_DIR, ROOT, ensureDir, loadSkills, readJson, writeFile } from '../scripts/lib.mjs';
+import { DIST_DIR, ROOT, ensureDir, loadSkills, readJson } from '../scripts/lib.mjs';
 
 const AGENTS = ['codex', 'claude', 'cursor', 'gemini', 'copilot', 'windsurf'];
 const DEFAULT_SOURCE = 'https://github.com/joktec/joktec-skills.git';
@@ -268,22 +268,6 @@ function executeOperations(operations, force, dryRun) {
   }
 }
 
-function writeManifest(project, pack, agents, skillIds, dryRun) {
-  const file = path.join(project, '.joktec-skills.json');
-  const existing = fs.existsSync(file) ? readJson(file) : {};
-  const manifest = {
-    package: '@joktec/skills',
-    version: pack.version,
-    installedAt: new Date().toISOString(),
-    agents: Array.from(new Set([...(existing.agents || []), ...agents])).sort(),
-    skills: Array.from(new Set([...(existing.skills || []), ...skillIds])).sort(),
-    frameworkBaseline: pack.frameworkBaseline,
-    packageBaseline: pack.packageBaseline,
-  };
-  if (!dryRun) writeFile(file, JSON.stringify(manifest, null, 2));
-  return manifest;
-}
-
 function logo() {
   console.log(color.dim(`     ██╗ ██████╗ ██╗  ██╗████████╗███████╗ ██████╗
      ██║██╔═══██╗██║ ██╔╝╚══██╔══╝██╔════╝██╔════╝
@@ -346,15 +330,26 @@ function buildInstalledLines(project, operations, skillIds, dryRun) {
   ]);
 }
 
+function stripAnsi(value) {
+  return String(value).replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '');
+}
+
+function fitLine(value) {
+  const width = Math.max(40, (output.columns || 100) - 4);
+  const plain = stripAnsi(value);
+  if (plain.length <= width) return value;
+  return `${plain.slice(0, width - 1)}…`;
+}
+
 function renderMultiSelect(items, cursor, selected, message) {
-  readline.cursorTo(output, 0);
-  readline.clearScreenDown(output);
-  console.log(`${color.green('◇')}  ${message} ${color.dim('(space to toggle, enter to confirm)')}`);
+  const lines = [`${color.green('◇')}  ${message} ${color.dim('(space to toggle, enter to confirm)')}`];
   for (let i = 0; i < items.length; i += 1) {
     const marker = selected.has(items[i].value) ? color.green('●') : '○';
     const pointer = i === cursor ? color.cyan('›') : ' ';
-    console.log(`│ ${pointer} ${marker} ${items[i].label}`);
+    lines.push(`│ ${pointer} ${marker} ${fitLine(items[i].label)}`);
   }
+  output.write(`${lines.join('\n')}\n`);
+  return lines.length;
 }
 
 async function multiSelect(items, defaults, message) {
@@ -362,12 +357,22 @@ async function multiSelect(items, defaults, message) {
 
   const selected = new Set(defaults);
   let cursor = 0;
+  let renderedLines = 0;
   output.write('\n');
   readline.emitKeypressEvents(input);
   input.setRawMode(true);
 
   try {
     return await new Promise(resolve => {
+      const redraw = () => {
+        if (renderedLines) {
+          readline.moveCursor(output, 0, -renderedLines);
+          readline.cursorTo(output, 0);
+          readline.clearScreenDown(output);
+        }
+        renderedLines = renderMultiSelect(items, cursor, selected, message);
+      };
+
       const onKey = (str, key) => {
         if (key.name === 'c' && key.ctrl) {
           input.setRawMode(false);
@@ -383,15 +388,16 @@ async function multiSelect(items, defaults, message) {
         if (key.name === 'return') {
           input.off('keypress', onKey);
           input.setRawMode(false);
+          if (renderedLines) readline.moveCursor(output, 0, -renderedLines);
           readline.cursorTo(output, 0);
           readline.clearScreenDown(output);
           resolve(Array.from(selected));
           return;
         }
-        renderMultiSelect(items, cursor, selected, message);
+        redraw();
       };
 
-      renderMultiSelect(items, cursor, selected, message);
+      redraw();
       input.on('keypress', onKey);
     });
   } finally {
@@ -410,6 +416,7 @@ async function confirm(message, yes) {
 
 async function addCommand(args) {
   const { pack } = loadSkills();
+  const pkg = readJson(path.join(ROOT, 'package.json'));
   const project = path.resolve(args.project || '.');
   const source = consumeSourceToken(args);
   const agents = parseAgents(args.agent);
@@ -427,11 +434,12 @@ async function addCommand(args) {
     selected = await multiSelect(
       pack.skills.map(skill => ({
         value: skill.id,
-        label: `${skill.id} ${color.dim(`(${skill.packages.join(', ')})`)}`,
+        label: `${skill.id} (${skill.packages.join(', ')})`,
       })),
       pack.skills.filter(skill => skill.requiredByDefault).map(skill => skill.id),
       'Select skills to install',
     );
+    step('Select skills to install', selected.join(', '));
   } else {
     selected = resolveSkillIds(pack, requested, Boolean(args.all));
     step('Select skills to install', selected.join(', '));
@@ -457,15 +465,13 @@ async function addCommand(args) {
   }
 
   executeOperations(operations, Boolean(args.force), Boolean(args['dry-run']));
-  const manifest = writeManifest(project, pack, agents, resolution.selected, Boolean(args['dry-run']));
 
   step(args['dry-run'] ? 'Dry run complete' : 'Installation complete');
   box(
     `${args['dry-run'] ? 'Planned' : 'Installed'} ${resolution.selected.length} skills`,
     buildInstalledLines(project, operations, resolution.selected, Boolean(args['dry-run'])),
   );
-  console.log(`│  ${color.dim(`Manifest: ${displayPath(path.join(project, '.joktec-skills.json'))}`)}`);
-  console.log(`│  ${color.dim(`@joktec/skills ${manifest.version}`)}`);
+  console.log(`│  ${color.dim(`@joktec/skills ${pkg.version}`)}`);
   console.log('│');
   done('Review skills before use; they run with full agent permissions.');
 }

package/dist/claude/skills/joktec-adapter-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-adapter-skill
 description: Use when wiring or using JokTec adapter packages @joktec/cacher, @joktec/mailer, @joktec/notifier, or @joktec/storage for cache, mail delivery, push notifications, object storage, config-driven clients, and app-neutral adapter services.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Adapter Skill
@@ -20,6 +24,7 @@ Use this skill for pluggable external capability adapters.
 - Use validated config and `conId` where supported.
 - Keep secrets and credentials in app config or runtime environment, never in code.
 - Prefer adapter services over direct SDK usage in app services.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/claude/skills/joktec-adapter-skill/references/adapters.md

@@ -1,12 +1,40 @@
 # Adapter Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/adapters/README.md`
+- `packages/adapters/AGENTS.md`
+- `packages/adapters/<package>/README.md`
+- `packages/adapters/<package>/src/index.ts`
+- package module/config/service files under `src/`
+
 ## Runtime Pattern
 
 Adapters are global Nest modules. Services own native client creation and expose package-specific operations.
 
+Most adapters follow `AbstractClientService`: config is validated, native clients are created by the service, `conId` selects the connection, and shutdown/retry/debug behavior should remain package-owned.
+
 ## Package Notes
 
 - Cacher: choose local, Redis, or Memcached stores based on runtime config.
 - Mailer: centralize mail transport configuration in the service that owns outbound email.
 - Notifier: keep push provider configuration outside app business logic.
 - Storage: keep storage metadata and object operations behind the adapter service.
+
+## Best Practices
+
+- Import adapter modules in the application layer, then inject services into domain services.
+- Keep provider credentials, endpoints, bucket names, SMTP secrets, and push credentials in runtime config.
+- Keep business payload composition in the consuming app. The adapter should send/cache/store, not decide product semantics.
+- Use `conId` for multiple providers or tenants instead of creating ad-hoc service instances.
+- Normalize provider errors at the package/app boundary so controllers do not branch on SDK-specific messages.
+- Mock SDK clients in unit tests; run live provider checks only in explicit integration or consumer harness tests.
+
+## Anti-Patterns
+
+- Do not put email template business rules inside `@joktec/mailer`.
+- Do not hardcode S3 buckets, Redis URLs, SMTP credentials, or notification tokens in source.
+- Do not bypass adapter services by importing provider SDK clients directly throughout the app.
+- Do not assume every adapter has identical method names; read each package README/source before calling.

package/dist/claude/skills/joktec-broker-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-broker-skill
 description: Use when wiring or using JokTec broker packages @joktec/kafka, @joktec/rabbit, @joktec/sqs, or @joktec/redcast, including client config, producer decorators, consumer loaders, message handlers, auto-binding, and app-level broker flows.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Broker Skill
@@ -20,6 +24,7 @@ Use this skill for message broker packages.
 - Use broker decorators for transport wiring, not for domain policy.
 - Preserve config-driven client selection and `conId` when available.
 - Keep topic, queue, and routing names explicit in app configuration or decorators.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/claude/skills/joktec-broker-skill/references/brokers.md

@@ -1,12 +1,41 @@
 # Broker Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/brokers/README.md`
+- `packages/brokers/AGENTS.md`
+- `packages/brokers/<package>/README.md`
+- `packages/brokers/<package>/src/index.ts`
+- package decorators, loaders, config, and service files under `src/`
+
 ## Runtime Pattern
 
 Broker services follow `AbstractClientService` lifecycle. Loader classes discover decorator metadata after module initialization. Apps define producers, consumers, and message semantics.
 
+Use broker packages for transport wiring, not for business workflow ownership. The consuming app owns event names, payload contracts, idempotency, retry policy, dead-letter behavior, and handler semantics.
+
 ## Package Notes
 
 - Kafka: check topic existence and broker advertised listeners in local development.
 - RabbitMQ: use module options and decorators for exchanges, queues, and bindings.
 - SQS: local ElasticMQ-style environments may require queues to exist before consumers start.
 - Redcast: use Redis-backed list, stream, or pub/sub behavior when a lightweight broker is enough.
+
+## Best Practices
+
+- Start consumers only in processes that should own subscriptions.
+- Keep producer and consumer payload DTOs versionable and explicit.
+- Use config paths or module options for topic/queue names when supported.
+- Make handlers idempotent; brokers may redeliver.
+- Add observable effects for consumer tests rather than asserting log text.
+- Keep broker health/preflight checks separate from business request handling.
+- In local stacks, verify broker-specific infrastructure: Kafka topics, Rabbit exchanges/queues, SQS queues, Redis password/db.
+
+## Anti-Patterns
+
+- Do not hide domain workflows inside decorators or broker package services.
+- Do not assume auto-create topic/queue behavior unless the package and local broker support it.
+- Do not run the same consumer group/queue owner in every process by accident.
+- Do not swallow message handling errors without retry/dead-letter visibility.

package/dist/claude/skills/joktec-common-skill/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: joktec-common-skill
 description: Use when implementing or wiring @joktec/core, @joktec/utils, or @joktec/cron in a consumer app, especially BaseController, BaseService, pagination, config, client lifecycle, bootstrap, cron decorators, or utility helpers.
+metadata:
+  dependencies:
+    - joktec-framework-skill
 ---
 
 # JokTec Common Skill
@@ -21,6 +24,7 @@ Use this skill for shared framework primitives, low-level helpers, cron utilitie
 - Use page, offset, or cursor pagination contracts from core; let database packages execute storage-specific pagination.
 - Use `AbstractClientService` patterns for client packages that need config, lifecycle, retry, and `conId`.
 - Use `@joktec/utils` for shared helpers instead of duplicating conversion, validation, hashing, or UUID logic.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## References
 

package/dist/claude/skills/joktec-common-skill/references/core.md

@@ -1,19 +1,75 @@
 # Common Core Usage
 
+## Source Lookup
+
+When blocked, inspect these framework files before guessing:
+
+- `packages/common/core/README.md`
+- `packages/common/core/AGENTS.md`
+- `packages/common/core/src/index.ts`
+- `packages/common/core/src/abstractions/*`
+- `packages/common/core/src/models/base.request.ts`
+- `packages/common/core/src/models/base.response.ts`
+- `packages/common/core/src/models/paginations/*`
+- `packages/common/core/src/client/abstract-client.service.ts`
+- `packages/common/core/src/infras/application.ts`
+- `packages/common/core/src/modules/*`
+
 ## Runtime Bootstrap
 
 Use the application bootstrap helpers from `@joktec/core` for gateway and microservice runtimes. Keep runtime behavior config-driven.
 
+Best practice:
+
+- Use `Application.bootstrap(AppModule)` instead of hand-rolling Nest bootstrap unless the consumer app has a specific runtime reason.
+- Keep gateway-only behavior in gateway runtime modules and microservice-only behavior in micro runtime modules.
+- Register framework modules through their dynamic module APIs when provided.
+- Do not duplicate config parsing, logger setup, metrics setup, or process lifecycle hooks in consumer apps.
+
 ## CRUD Abstractions
 
 - `BaseController` creates standard REST CRUD endpoints for DTO-backed resources.
 - `BaseService` delegates repository operations through the shared repository contract.
 - `ClientController` and `ClientService` provide generated microservice CRUD patterns.
 
+Use BaseController/BaseService when the resource follows standard CRUD. Avoid them when the endpoint has domain-specific command semantics, multi-step transactions, or non-standard authorization that would make the generic abstraction obscure behavior.
+
+Controller checklist:
+
+- choose the DTO/entity class intentionally
+- set `paginationMode` for the representative Swagger response shape
+- use `customDto.paginationDto` only when the built-in page/offset/cursor response does not represent the API
+- keep auth/guards/interceptors consistent with app conventions
+- avoid putting business branching in controller methods when it belongs in the service
+
 ## Pagination
 
 Request priority is cursor, then offset, then page. `BaseController.paginationMode` affects Swagger response shape; runtime selection remains request-driven unless the app service narrows it.
 
+Best practice:
+
+- Use page pagination for admin tables and simple back-office views.
+- Use offset pagination for mobile-style load-more when the data set is moderate and stable enough.
+- Use cursor pagination for feeds, timelines, frequently inserted lists, or large tables.
+- Do not document cursor support for a resource unless the underlying repository package actually supports it.
+- When using cursor mode, ensure the database layer has stable sort keys and tie-breakers.
+
 ## Client Lifecycle
 
 Use `ClientConfig`, `AbstractClientService`, and `conId` when building or consuming packages that support multiple client connections.
+
+Client package checklist:
+
+- config class validates all required runtime options
+- service startup fails clearly when the native client cannot initialize
+- shutdown closes native connections only when initialized
+- `conId` is preserved through service/repository calls
+- logs do not leak credentials or full connection strings
+- retries and debug behavior are config-driven
+
+## Do Not
+
+- Do not import concrete package or app code into `@joktec/core`.
+- Do not bypass shared pagination contracts with ad-hoc response shapes for standard CRUD.
+- Do not add new public symbols without exporting them through `src/index.ts`.
+- Do not silently swallow bootstrap/client initialization failures.

package/dist/claude/skills/joktec-common-skill/references/utils-cron.md

@@ -6,12 +6,40 @@ Use `@joktec/utils` for common generators, validators, converters, hashing helpe
 
 Prefer package helpers over app-local reimplementation when behavior should stay consistent across services.
 
+Source lookup:
+
+- `packages/common/utils/README.md`
+- `packages/common/utils/src/index.ts`
+- `packages/common/utils/src/helpers/*`
+- `packages/common/utils/src/validators/*`
+- `packages/common/utils/src/constants/*`
+
+Best practice:
+
+- Use shared validators from `@joktec/utils` when building schema-first entity/schema decorators.
+- Use shared generators for IDs, tokens, random values, and hashes when consistency matters.
+- Keep utility usage deterministic in tests; mock time/randomness where needed.
+- Do not add framework-level dependencies to `utils`.
+
 ## Cron
 
 Use `@joktec/cron` when a consumer app needs scheduled jobs, job worker contracts, or decorator-driven cron registration.
 
 Keep job business logic in the consumer app. The package provides scheduling abstractions, not domain behavior.
 
+Source lookup:
+
+- `packages/common/cron/README.md`
+- `packages/common/cron/src/index.ts`
+- cron decorators, models, scheduler services, and worker contracts under `src/`
+
+Best practice:
+
+- Keep job names, schedules, concurrency, and retry behavior visible in the consumer app.
+- Make cron handlers idempotent.
+- Avoid enabling the same cron owner in multiple processes unless the package/app has explicit locking semantics.
+- Treat cron runtime as infrastructure orchestration; domain writes still belong in app services/repositories.
+
 ## Types
 
 Use `@joktec/types` when a consumer workflow needs generated JokTec package config schema/type artifacts. Treat the framework repository as source-of-truth for the generated schema shape.

package/dist/claude/skills/joktec-database-extended-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-database-extended-skill
 description: Use when working with extended JokTec database packages @joktec/elastic, @joktec/arango, or @joktec/bigquery in a consumer app, including app-neutral client setup, config-driven lifecycle, and package-specific query/service usage.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Extended Database Skill
@@ -19,6 +23,7 @@ Use this skill for database clients that are not Mongo or MySQL.
 - Use package services for client lifecycle and connection config.
 - Do not claim parity with Mongo/MySQL repository behavior unless the package implements it.
 - Use package README and source as final truth before adding advanced behavior.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/claude/skills/joktec-database-extended-skill/references/extended-databases.md

@@ -1,5 +1,15 @@
 # Extended Database Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/databases/README.md`
+- `packages/databases/AGENTS.md`
+- `packages/databases/<package>/README.md`
+- `packages/databases/<package>/src/index.ts`
+- package config/module/service files under `src/`
+
 ## Package Boundaries
 
 Extended database packages expose reusable clients and helpers for specific data systems. They should not contain consumer app schemas or business-specific query policy.
@@ -9,3 +19,17 @@ Extended database packages expose reusable clients and helpers for specific data
 - Elastic may depend on `@joktec/http` for HTTP-backed behavior.
 - Arango and BigQuery are separate client packages; verify the README/source before assuming repository-like CRUD support.
 - Use local package tests or consumer harnesses only when the target service stack is available.
+
+## Best Practices
+
+- Treat these packages as client wrappers unless source explicitly exposes a repository abstraction.
+- Keep index names, dataset names, query templates, and domain-specific projections in the consumer app.
+- Validate credentials and endpoints through config; never commit service account data.
+- Keep retries, timeouts, and debug logging visible in config.
+- Use provider-specific tests/mocks for package logic and live stack tests only when credentials/services are intentionally available.
+
+## Anti-Patterns
+
+- Do not apply MongoRepo/MysqlRepo assumptions to Elastic/Arango/BigQuery.
+- Do not introduce app schemas or business query policy into reusable database clients.
+- Do not claim support for a provider feature unless the package source or README shows it.

package/dist/claude/skills/joktec-framework-skill/SKILL.md

@@ -25,6 +25,7 @@ Start here when a task mentions JokTec generally, multiple `@joktec/*` packages,
 - Prefer config-driven module setup and `conId` when a package supports multiple clients.
 - Preserve NestJS module boundaries, dependency injection, lifecycle hooks, and exported package APIs.
 - Do not invent behavior for unfinished or missing packages.
+- If a focused skill is loaded without this entrypoint, still apply source-first lookup before assuming APIs.
 
 ## Reference
 

package/dist/claude/skills/joktec-framework-skill/references/framework-map.md

@@ -1,5 +1,24 @@
 # JokTec Framework Map
 
+## Source-First Operating Protocol
+
+Treat this skill pack as curated guidance, not the final implementation truth. When a task is unclear, or when a package API seems different from the skill text:
+
+1. Inspect the consumer project first to understand the package versions and local usage pattern.
+2. Prefer local framework source at `../joktec-framework` when available.
+3. Read package `README.md`, nearest `AGENTS.md`, and `src/index.ts` before changing code.
+4. If local source is unavailable, use `https://github.com/joktec/joktec-framework` as fallback.
+5. Do not invent behavior that is not visible in framework source or package docs.
+6. If package docs and source conflict, source code wins and the mismatch should be treated as documentation drift.
+
+High-value source files:
+
+- `AGENTS.md` and `docs/agents/*` for framework-level architecture and runtime policy.
+- `packages/<family>/AGENTS.md` for family boundaries.
+- `packages/<family>/<package>/README.md` for developer-facing usage.
+- `packages/<family>/<package>/src/index.ts` for public API.
+- Package config/module/service/repository files for real runtime behavior.
+
 ## Package Families
 
 - `@joktec/core`: bootstrap, config, logger, metrics, guards, base abstractions, transports, pagination, Bull.
@@ -17,9 +36,24 @@
 
 Consumer apps depend on concrete `@joktec/*` packages. Concrete packages usually depend on `@joktec/core` and `@joktec/utils`. Keep app-specific schemas, handlers, and business semantics outside reusable packages.
 
+Do not reverse the dependency direction:
+
+- reusable packages must not import from `apps/`
+- `common` packages must not depend on concrete adapters/brokers/databases
+- consumer apps own business workflows, DTO composition, schemas/entities, queue names, topics, and provider credentials
+
 ## Common Consumer App Pattern
 
 1. Register package modules in the app module or repository module.
 2. Keep app schemas/entities and app repositories in the consumer app.
 3. Extend the package repository base class when the package provides one.
 4. Use `BaseService`, `BaseController`, or transport helpers from `@joktec/core` when the app follows standard CRUD or message patterns.
+
+## Skill Selection
+
+- Use `joktec-common-skill` for BaseController/BaseService/config/pagination/client lifecycle/utils/cron.
+- Use `joktec-mongo-skill` when the resource uses Mongo schemas, MongoRepo, Typegoose decorators, plugins, or ObjectId-safe queries.
+- Use `joktec-mysql-skill` when the resource uses TypeORM entities, MysqlRepo, SQL dialect behavior, transactions, or schema-first column decorators.
+- Use broker/adapter/integration/tool skills for provider wiring; keep business semantics in the consumer app.
+
+When using the ecosystem `npx skills` installer, install `joktec-framework-skill` and `joktec-common-skill` together with any focused package skill. The current ecosystem installer does not auto-resolve dependencies from frontmatter.

package/dist/claude/skills/joktec-integration-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-integration-skill
 description: Use when wiring or using JokTec integration packages @joktec/firebase or @joktec/gpt, including validated config, SDK client lifecycle, app-neutral integration services, credentials handling, and consumer app composition.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Integration Skill
@@ -18,6 +22,7 @@ Use this skill for third-party integration packages.
 - Use package services instead of direct SDK initialization in app code.
 - Preserve app-neutral service behavior; consumer apps own domain workflows.
 - Verify current package README/source before relying on advanced provider features.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## Reference
 

package/dist/claude/skills/joktec-integration-skill/references/integrations.md

@@ -1,9 +1,38 @@
 # Integration Usage
 
+## Source Lookup
+
+When blocked, inspect:
+
+- `packages/integrations/README.md`
+- `packages/integrations/AGENTS.md`
+- `packages/integrations/<package>/README.md`
+- `packages/integrations/<package>/src/index.ts`
+- package config/module/service files under `src/`
+
 ## Firebase
 
 Use the integration module and service to initialize Firebase Admin clients from validated config. Keep credential files local or environment-provided.
 
+Best practice:
+
+- Keep service account JSON, private keys, and project credentials out of git.
+- Prefer environment-specific config or ignored local credential files.
+- Keep notification/user/storage/product semantics in the consumer app.
+- Mock Firebase Admin SDK in package tests; use live credentials only in explicit integration environments.
+
 ## GPT
 
 Use the integration package for reusable GPT client setup. Keep prompt/business policy in the consumer app, not in the generic package.
+
+Best practice:
+
+- Keep prompts, model choice policy, tool schemas, and product safety rules in the consumer app.
+- Keep API keys in secret management or environment config.
+- Verify current package completeness before relying on advanced APIs; `@joktec/gpt` may lag behind provider SDK changes.
+
+## Anti-Patterns
+
+- Do not commit real credential files.
+- Do not encode product-specific prompts or notification logic into the reusable integration package.
+- Do not assume provider SDK behavior without checking package source and provider docs when APIs are unstable.

package/dist/claude/skills/joktec-mongo-skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: joktec-mongo-skill
 description: Use when working with @joktec/mongo in a consumer app, including MongoModule setup, Typegoose schema decorators, MongoRepo, MongoService, MongoHelper, plugins, ObjectId/query safety, soft delete, strict references, and cursor pagination.
+metadata:
+  dependencies:
+    - joktec-framework-skill
+    - joktec-common-skill
 ---
 
 # JokTec Mongo Skill
@@ -15,6 +19,7 @@ Use this skill for MongoDB-backed resources that rely on JokTec's Mongoose/Typeg
 - Preserve `conId` when the app has multiple Mongo connections.
 - Use schema-first decorators when a schema class should be reused as a DTO source.
 - Treat ObjectId casting and regex behavior as safety-sensitive.
+- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
 
 ## References