📍 feat: always-apply frontmatter: auto-prime skills every turn (danny-avila#12746)

* 🔁 refactor: Rebase always-apply work onto merged structured-frontmatter columns

Phase 6 (disable-model-invocation / user-invocable / allowed-tools)
landed first on feat/agent-skills. Reconcile this branch with the new
mainline:

- Thread alwaysApplySkillPrimes through unionPrimeAllowedTools alongside
  manualSkillPrimes, applying the combined MAX_PRIMED_SKILLS_PER_TURN
  ceiling before loading tools.
- Add `_id` to ResolvedAlwaysApplySkill to match Phase 6's
  ResolvedManualSkill shape (read_file name-collision protection).
- Register 'always-apply' in ALLOWED_FRONTMATTER_KEYS / FRONTMATTER_KIND
  so Phase 6's validator recognizes it.
- Drop frontmatter from the listSkillsByAccess projection; the backfill
  helper remains as defensive code but its read path is no longer
  exercised on summary rows (no legacy rows exist — the branch never
  shipped), saving ~200KB per page.
- Retire the corresponding "backfills legacy on summaries" test.
- Plumb listAlwaysApplySkills through the JS controllers + endpoint
  initializer so the always-apply resolver sees a real DB method.

* 🧹 fix: Dedupe manual/always-apply overlap, share YAML util, tidy comments

Addresses review findings:

- Cross-list dedup: when a user $-invokes a skill that is also marked
  always-apply, the always-apply copy is now dropped so the same
  SKILL.md body never primes twice in one turn. Manual wins (explicit
  intent, closer to the user message). Dedup runs in both
  initializeAgent (so persisted user-bubble pills stay in sync) and
  injectSkillPrimes (defense-in-depth at splice time). New test cases
  cover single-overlap, partial-overlap, and dedup-before-cap.
- DRY: extract stripYamlTrailingComment to
  packages/data-schemas/src/utils/yaml.ts; packages/api/src/skills/import.ts
  now imports the shared helper. Also drop the redundant inner
  stripYamlTrailingComment call inside parseBooleanScalar — the call
  site already strips.
- Mark injectManualSkillPrimes as @deprecated in favor of
  injectSkillPrimes (kept for external consumers of @librechat/api).
- Document SKILL_TRIGGER_MODEL as forward-looking plumbing for the
  model-invoked path rather than leaving it as a bare unused export.
- Replace the stale "frontmatter is included" comment on
  listSkillsByAccess with an accurate explanation of why it was
  intentionally excluded.

* 🔒 fix: Include always-apply primes in skillPrimedIdsByName + clear alwaysApply on body opt-out

Two bugs flagged by Codex review:

P1 (read_file): `manualSkillPrimedIdsByName` only carried manual-invocation
primes, so an always-apply skill with `disable-model-invocation: true`
was blocked from reading its own bundled files, and same-name collisions
could resolve to a different doc than the one whose body got primed.
- Rename `buildManualSkillPrimedIdsByName` → `buildSkillPrimedIdsByName`
  (accepts both manual + always-apply prime arrays).
- Rename the configurable field `manualSkillPrimedIdsByName` →
  `skillPrimedIdsByName` throughout the plumbing (skillConfigurable.ts,
  handlers.ts, CJS callers, tests).
- Overlap resolution: manual wins on the rare edge case where the same
  name appears in both arrays (upstream dedup should prevent this, but
  defensive merging treats manual as authoritative).
- New tests: (1) gate-relaxation fires for always-apply primes, (2) `_id`
  pinning works for always-apply same-name collisions.

P2 (updateSkill): when a body update had no `always-apply:` key,
`extractAlwaysApplyFromBody` returned `absent` and the column was left
untouched. A skill that was once `alwaysApply: true` would keep
auto-priming even after its SKILL.md no longer declared the flag.
- Treat `absent` as a positive "not always-apply" declaration when the
  body is explicitly submitted; flip the column to `false`.
- Explicit top-level `alwaysApply` still wins (three-source precedence
  unchanged).
- New tests: body removes key → false, body has no frontmatter at all →
  false, explicit + body-without-key → explicit wins.

* 🧵 refactor: Collapse duplicate prime types + tighten parse + test hygiene

Sanity-check review follow-ups:

- Collapse `ResolvedManualSkill` / `ResolvedAlwaysApplySkill` into a
  single `ResolvedSkillPrime` canonical interface with two backward-
  compatible type aliases. Both resolvers feed the same pipeline stages
  (injectSkillPrimes, unionPrimeAllowedTools, buildSkillPrimedIdsByName);
  the per-source distinction lives on `additional_kwargs.trigger`, not
  on the resolver output.
- Move the `always-apply` branch in `parseFrontmatter` to operate on the
  raw post-colon text. The outer `unquoteYaml` was fine today because
  it's idempotent on non-quoted strings, but running it twice (once per
  line, once after stripping the inline comment) would be fragile if the
  unquoter ever grows richer YAML-escape handling.
- Add the missing `alwaysApplyDedupedFromManual: 0` field to the
  `injectSkillPrimes` mocks in `openai.spec.js` and `responses.unit.spec.js`
  so they match the full `InjectSkillPrimesResult` contract.
- Insert the blank line between the `unionPrimeAllowedTools` and
  `resolveAlwaysApplySkills` describe blocks.

* 🔧 fix(tsc): Cast mock.calls via `unknown` for strict tuple destructure

`getSkillByName.mock.calls[0]` is typed as `[]` by jest's generic default;
a direct cast to `[string, ..., ...]` fails TS2352 under `--noEmit` even
though the runtime shape matches. Go through `as unknown as [...]` like
the earlier test in the same file so CI's type-check step stays green.

* 🪢 fix: Propagate skillPrimedIdsByName into handoff agent tool context

Handoff agents go through the same `initializeAgent` flow as the primary
(with `listAlwaysApplySkills` now plumbed), so they resolve their own
`manualSkillPrimes` and `alwaysApplySkillPrimes` — but the
`agentToolContexts.set(...)` for handoff agents didn't carry
`skillPrimedIdsByName` into the per-agent context.

That meant `handleReadFileCall` fell back to the full ACL set + a
`prefer*` flag for handoff agents: same-name collisions could resolve to
a different doc than the one whose body got primed, and a
`disable-model-invocation: true` skill primed via manual `$` or
always-apply inside the handoff flow would be blocked from reading its
own bundled files.

Build the map via `buildSkillPrimedIdsByName(config.manualSkillPrimes,
config.alwaysApplySkillPrimes)` for every handoff tool context so
`read_file` behaves identically across primary and handoff agents.

Author: danny-avila

api/app/clients/BaseClient.js

@@ -508,6 +508,23 @@ class BaseClient {
           userMessage.manualSkills = skills;
         }
       }
+      /**
+       * Persist the names of skills auto-primed this turn via `always-apply`
+       * frontmatter so `ManualSkillPills` can render pinned-variant badges
+       * on the user bubble that survive reload and history render. Frozen
+       * at turn time (not reconstructed from `Skill.alwaysApply` at render
+       * time) because the flag is mutable — historical turns must keep
+       * their audit trail even if an admin flips `alwaysApply` off later.
+       */
+      const alwaysApplySkillPrimes = this.options.agent?.alwaysApplySkillPrimes;
+      if (Array.isArray(alwaysApplySkillPrimes) && alwaysApplySkillPrimes.length > 0) {
+        const names = alwaysApplySkillPrimes
+          .map((p) => p?.name)
+          .filter((n) => typeof n === 'string' && n.length > 0);
+        if (names.length > 0) {
+          userMessage.alwaysAppliedSkills = names;
+        }
+      }
       userMessagePromise = this.saveMessageToDatabase(userMessage, saveOptions, user).catch(
         (err) => {
           logger.error('[BaseClient] Failed to save user message:', err);

api/server/controllers/agents/__tests__/openai.spec.js

@@ -59,6 +59,14 @@ jest.mock('@librechat/api', () => ({
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
   extractManualSkills: jest.fn().mockReturnValue(undefined),
+  injectSkillPrimes: jest.fn().mockReturnValue({
+    initialMessages: [],
+    indexTokenCountMap: {},
+    inserted: 0,
+    insertIdx: -1,
+    alwaysApplyDropped: 0,
+    alwaysApplyDedupedFromManual: 0,
+  }),
   buildNonStreamingResponse: jest.fn().mockReturnValue({ id: 'resp-123' }),
   createOpenAIStreamTracker: jest.fn().mockReturnValue({
     addText: jest.fn(),

api/server/controllers/agents/__tests__/responses.unit.spec.js

@@ -61,6 +61,14 @@ jest.mock('@librechat/api', () => ({
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
   extractManualSkills: jest.fn().mockReturnValue(undefined),
+  injectSkillPrimes: jest.fn().mockReturnValue({
+    initialMessages: [],
+    indexTokenCountMap: {},
+    inserted: 0,
+    insertIdx: -1,
+    alwaysApplyDropped: 0,
+    alwaysApplyDedupedFromManual: 0,
+  }),
   createToolExecuteHandler: jest.fn().mockReturnValue({ handle: jest.fn() }),
   // Responses API
   writeDone: jest.fn(),

api/server/controllers/agents/client.js

@@ -28,7 +28,7 @@ const {
   filterMalformedContentParts,
   countFormattedMessageTokens,
   hydrateMissingIndexTokenCounts,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   isSkillPrimeMessage,
   buildSkillPrimeContentParts,
 } = require('@librechat/api');
@@ -773,26 +773,41 @@ class AgentClient extends BaseClient {
       }
 
       /**
-       * Phase 3 manual skill priming — injected by user via `$` popover.
+       * Skill priming — both manual ($ popover) and always-apply (frontmatter).
        *
-       * Splice + index-shift logic lives in `injectManualSkillPrimes`
+       * Splice + index-shift logic lives in `injectSkillPrimes`
        * (packages/api/src/agents/skills.ts) so the delicate position math
-       * can be unit-tested in TS without standing up AgentClient. Runs for
-       * both single-agent and multi-agent runs; how primes interact with
-       * handoff / added-convo agents' per-agent state is an agents-SDK
-       * concern, not this layer's to gate.
+       * can be unit-tested in TS without standing up AgentClient. The
+       * resolver enforces a combined ceiling (manual-first, always-apply
+       * truncated first when over cap) before reaching here; the splice
+       * re-applies the cap as defense-in-depth. Runs for both single-
+       * agent and multi-agent runs; how primes interact with handoff /
+       * added-convo agents' per-agent state is an agents-SDK concern,
+       * not this layer's to gate.
        */
       const manualSkillPrimes = this.options.agent?.manualSkillPrimes;
-      if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-        const primeResult = injectManualSkillPrimes({
+      const alwaysApplySkillPrimes = this.options.agent?.alwaysApplySkillPrimes;
+      if (
+        (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+        (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+      ) {
+        const primeResult = injectSkillPrimes({
           initialMessages,
           indexTokenCountMap,
           manualSkillPrimes,
+          alwaysApplySkillPrimes,
         });
         indexTokenCountMap = primeResult.indexTokenCountMap;
         if (primeResult.inserted > 0) {
+          const manualNames = (manualSkillPrimes ?? []).map((p) => p.name);
+          const alwaysApplyNames = (alwaysApplySkillPrimes ?? []).map((p) => p.name);
           logger.debug(
-            `[AgentClient] Primed ${primeResult.inserted} manual skill(s) at message index ${primeResult.insertIdx}: ${manualSkillPrimes.map((p) => p.name).join(', ')}`,
+            `[AgentClient] Primed ${primeResult.inserted} skill(s) at message index ${primeResult.insertIdx} — manual: [${manualNames.join(', ')}], always-apply: [${alwaysApplyNames.join(', ')}]`,
+          );
+        }
+        if (primeResult.alwaysApplyDropped > 0) {
+          logger.warn(
+            `[AgentClient] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
           );
         }
       }
@@ -915,28 +930,40 @@ class AgentClient extends BaseClient {
       await runAgents(initialMessages);
 
       /**
-       * Surface a completed `skill` tool_call content part per manually-
-       * invoked skill so the existing `SkillCall` frontend renderer shows
+       * Surface a completed `skill` tool_call content part per *manually*-
+       * primed skill so the existing `SkillCall` frontend renderer shows
        * a "Skill X loaded" card on the assistant response. Applied after
        * the graph finishes to avoid clashing with the aggregator's own
        * per-step content indexing. Prepended (not appended) so cards sit
        * above the model's output — priming ran before the turn, the
        * reply follows.
        *
-       * Live streaming display of cards is handled on the user side via
-       * `ManualSkillPills` reading the message's `manualSkills` field;
-       * no separate SSE emit is needed here, and trying to stream a
-       * mid-run tool_call at index 0 collided with the LLM's first text
-       * content, while emitting at a sparse offset pushed the card below
-       * the reply on finalize. Post-run unshift keeps the final
+       * Always-apply primes intentionally do NOT emit assistant-side
+       * cards. `extractInvokedSkillsFromPayload` scans history for
+       * `skill` tool_calls and feeds `primeInvokedSkills`, which is
+       * Phase 3's sticky-re-prime path — that's the right behavior for
+       * manual (user picked `$skill` once; re-prime on every subsequent
+       * turn from history). For always-apply, `resolveAlwaysApplySkills`
+       * already re-primes every turn from fresh DB state, so persisting
+       * the card would cause the skill body to get primed twice per
+       * turn starting on turn 2. The user-facing acknowledgement for
+       * always-apply lives on the user bubble as the pinned
+       * `ManualSkillPills` row (`message.alwaysAppliedSkills`), which
+       * is the durable signal the user wants: "this skill auto-primes".
+       *
+       * Live streaming display of manual user-bubble pills is handled
+       * by `ManualSkillPills` reading `message.manualSkills`. No
+       * separate SSE emit is needed here; trying to stream a mid-run
+       * tool_call at index 0 collided with the LLM's first text
+       * content, while emitting at a sparse offset pushed the card
+       * below the reply on finalize. Post-run unshift keeps the final
        * responseMessage.content in the right order.
        */
-      const primedSkills = this.options.agent?.manualSkillPrimes;
-      if (primedSkills && primedSkills.length > 0) {
-        const primeParts = buildSkillPrimeContentParts(primedSkills, {
-          runId: this.responseMessageId ?? 'manual-skill',
-        });
-        this.contentParts.unshift(...primeParts);
+      const manualPrimed = this.options.agent?.manualSkillPrimes ?? [];
+      if (manualPrimed.length > 0) {
+        const runId = this.responseMessageId ?? 'skill-prime';
+        const manualParts = buildSkillPrimeContentParts(manualPrimed, { runId });
+        this.contentParts.unshift(...manualParts);
       }
 
       /** @deprecated Agent Chain */

api/server/controllers/agents/openai.js

@@ -29,7 +29,7 @@ const {
   buildNonStreamingResponse,
   createOpenAIStreamTracker,
   createOpenAIContentAggregator,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   isChatCompletionValidationFailure,
   discoverConnectedAgents,
   getRemoteAgentPermissions,
@@ -48,7 +48,7 @@ const {
 const {
   getSkillToolDeps,
   enrichWithSkillConfigurable,
-  buildManualSkillPrimedIdsByName,
+  buildSkillPrimedIdsByName,
 } = require('~/server/services/Endpoints/agents/skillDeps');
 const { getModelsConfig } = require('~/server/controllers/ModelController');
 const { logViolation } = require('~/cache');
@@ -246,6 +246,7 @@ const OpenAIChatCompletionController = async (req, res) => {
       getToolFilesByIds: db.getToolFilesByIds,
       getCodeGeneratedFiles: db.getCodeGeneratedFiles,
       listSkillsByAccess: db.listSkillsByAccess,
+      listAlwaysApplySkills: db.listAlwaysApplySkills,
       getSkillByName: db.getSkillByName,
     };
 
@@ -432,7 +433,10 @@ const OpenAIChatCompletionController = async (req, res) => {
           req,
           primaryConfig.accessibleSkillIds,
           undefined,
-          buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+          buildSkillPrimedIdsByName(
+            primaryConfig.manualSkillPrimes,
+            primaryConfig.alwaysApplySkillPrimes,
+          ),
         );
       },
       toolEndCallback,
@@ -450,17 +454,23 @@ const OpenAIChatCompletionController = async (req, res) => {
     let indexTokenCountMap = formatted.indexTokenCountMap;
 
     /**
-     * Inject manual skill primes so the model sees SKILL.md bodies for this
-     * turn — parity with AgentClient's chat path. OpenAI-compatible streaming
-     * uses its own tracker/aggregator shape, so the LibreChat-style card SSE
-     * events don't apply here; only the message-context part carries over.
+     * Inject manual + always-apply skill primes so the model sees SKILL.md
+     * bodies for this turn — parity with AgentClient's chat path. OpenAI-
+     * compatible streaming uses its own tracker/aggregator shape, so the
+     * LibreChat-style card SSE events don't apply here; only the
+     * message-context part carries over.
      */
     const manualSkillPrimes = primaryConfig.manualSkillPrimes;
-    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-      const primeResult = injectManualSkillPrimes({
+    const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+    if (
+      (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+      (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+    ) {
+      const primeResult = injectSkillPrimes({
         initialMessages: formattedMessages,
         indexTokenCountMap,
         manualSkillPrimes,
+        alwaysApplySkillPrimes,
       });
       indexTokenCountMap = primeResult.indexTokenCountMap;
     }

api/server/controllers/agents/responses.js

@@ -20,7 +20,7 @@ const {
   recordCollectedUsage,
   getTransactionsConfig,
   extractManualSkills,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   createToolExecuteHandler,
   discoverConnectedAgents,
   getRemoteAgentPermissions,
@@ -57,7 +57,7 @@ const {
 const {
   getSkillToolDeps,
   enrichWithSkillConfigurable,
-  buildManualSkillPrimedIdsByName,
+  buildSkillPrimedIdsByName,
 } = require('~/server/services/Endpoints/agents/skillDeps');
 const { getModelsConfig } = require('~/server/controllers/ModelController');
 const { logViolation } = require('~/cache');
@@ -373,6 +373,7 @@ const createResponse = async (req, res) => {
       getToolFilesByIds: db.getToolFilesByIds,
       getCodeGeneratedFiles: db.getCodeGeneratedFiles,
       listSkillsByAccess: db.listSkillsByAccess,
+      listAlwaysApplySkills: db.listAlwaysApplySkills,
       getSkillByName: db.getSkillByName,
     };
 
@@ -534,17 +535,23 @@ const createResponse = async (req, res) => {
     let indexTokenCountMap = formatted.indexTokenCountMap;
 
     /**
-     * Inject manual skill primes so the model sees SKILL.md bodies for this
-     * turn — parity with AgentClient's chat path. The Responses API uses its
-     * own response-builder shape, so LibreChat-style card SSE events don't
-     * apply; only the message-context part carries over.
+     * Inject manual + always-apply skill primes so the model sees SKILL.md
+     * bodies for this turn — parity with AgentClient's chat path. The
+     * Responses API uses its own response-builder shape, so LibreChat-
+     * style card SSE events don't apply; only the message-context part
+     * carries over.
      */
     const manualSkillPrimes = primaryConfig.manualSkillPrimes;
-    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-      const primeResult = injectManualSkillPrimes({
+    const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+    if (
+      (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+      (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+    ) {
+      const primeResult = injectSkillPrimes({
         initialMessages: formattedMessages,
         indexTokenCountMap,
         manualSkillPrimes,
+        alwaysApplySkillPrimes,
       });
       indexTokenCountMap = primeResult.indexTokenCountMap;
     }
@@ -607,7 +614,10 @@ const createResponse = async (req, res) => {
             req,
             primaryConfig.accessibleSkillIds,
             undefined,
-            buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+            buildSkillPrimedIdsByName(
+              primaryConfig.manualSkillPrimes,
+              primaryConfig.alwaysApplySkillPrimes,
+            ),
           );
         },
         toolEndCallback,
@@ -783,7 +793,10 @@ const createResponse = async (req, res) => {
             req,
             primaryConfig.accessibleSkillIds,
             undefined,
-            buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+            buildSkillPrimedIdsByName(
+              primaryConfig.manualSkillPrimes,
+              primaryConfig.alwaysApplySkillPrimes,
+            ),
           );
         },
         toolEndCallback,