@klhapp/skillmux 1.11.2 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.0](https://github.com/klhq/skillmux/compare/v1.11.2...v1.12.0) (2026-09-12)
+
+
+### Added
+
+* **manifest:** make the core skill cap configurable ([#190](https://github.com/klhq/skillmux/issues/190)) ([c5690b0](https://github.com/klhq/skillmux/commit/c5690b0f5fafda708ff87b991443e48bc02a4def))
+
 ## [1.11.2](https://github.com/klhq/skillmux/compare/v1.11.1...v1.11.2) (2026-09-05)
 
 

package/README.md

@@ -143,7 +143,8 @@ skillmux init \
   --yes
 ```
 
-Core pins apply to each configured target and stay capped at 25 skills. Add
+Core pins apply to each configured target and stay capped at 25 skills, or at
+`[core].limit` when the manifest sets one. Add
 project-specific skills from a repository root:
 
 ```sh

package/docs/cli.md

@@ -322,7 +322,7 @@ command prints the preserved path so cleanup remains an explicit user action.
 ## Core skills (`skillmux core`)
 
 Pin or unpin skills into `[core]`, the tier every target receives by
-default, capped at 25 skills:
+default, capped at 25 skills unless `[core].limit` raises it:
 
 ```sh
 skillmux core pin csv-formatter --yes

package/docs/concepts.md

@@ -55,7 +55,8 @@ one.
 
 One skill can serve different roles across machines or projects, but the
 shared manifest prevents conflicting core and project assignments. Core stays
-capped at 25 skills to protect agent startup context.
+capped at 25 skills by default to protect agent startup context. Raise or lower that with
+`limit` under `[core]` in the manifest.
 
 Delivery tiers do not select a deployment. A local Skillmux process can serve
 routed skills over stdio, while a shared Skillmux process can serve its server

package/docs/configuration.md

@@ -284,7 +284,8 @@ Lives at the vault root (a legacy `skr.toml` is still read if present, never wri
 
 ```toml
 [core]
-skills = ["csv-formatter"]           # pinned into every [targets.*] dir; capped at 25
+skills = ["csv-formatter"]           # pinned into every [targets.*] dir; capped at 25 by default
+# limit = 30                        # optional: raise or lower that cap
 
 [project.repo1]
 paths = ["/Users/you/code/repo1"]    # only synced for paths that exist locally
@@ -295,12 +296,13 @@ host = "workhorse"                    # optional; init adds the current hostname
 project_groups = ["repo1"]           # which [project.*] groups materialize into this target; [] means none
 ```
 
-- `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
+- `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills unless `[core].limit` says otherwise; `sync` fails if a listed skill id isn't actually in the vault.
+- `[core].limit` (optional, positive integer): the cap on `[core].skills`. Absent means 25. It lives in the manifest rather than machine config so the same manifest validates identically on every machine.
 - `[project.<group>].skills`: symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
 - `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`). `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
 - `[targets.<name>]`: one entry per adopted surface. Built-in names (`agent-skills`, `claude-code`, and `codex`) derive their directories from the name and omit `dir`. A custom target requires `dir`; create one with `skillmux target add <name> --dir <dir> --yes`. `skillmux target migrate --yes` removes legacy built-in `dir` fields without touching target files. An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
 
-**Pin/unpin without hand-editing.** `skillmux core pin`/`unpin` mutate `[core]` for you, and `skillmux project pin`/`unpin` mutate `[project.*]`, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
+**Pin/unpin without hand-editing.** `skillmux core pin`/`unpin` mutate `[core]` for you, and `skillmux project pin`/`unpin` mutate `[project.*]`, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under its cap) before writing anything:
 
 ```sh
 skillmux core pin csv-formatter --yes                                    # add to [core]

package/docs/skill-management.md

@@ -171,7 +171,7 @@ skillmux core unpin csv-formatter --yes
 
 One command can change several skill IDs. Skillmux validates the complete
 change before writing, so a conflict prevents the whole operation. Core stays
-capped at 25 skills.
+capped at 25 skills by default, which `[core].limit` overrides.
 
 Run `skillmux sync` after a direct pin or unpin command.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.11.2",
+  "version": "1.12.0",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/init.ts

@@ -257,9 +257,10 @@ export function planInitManifest(
       ),
     },
   };
-  if (manifest.core.skills.length > CORE_SKILL_LIMIT) {
+  const effectiveLimit = manifest.core.limit ?? CORE_SKILL_LIMIT;
+  if (manifest.core.skills.length > effectiveLimit) {
     throw new Error(
-      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${CORE_SKILL_LIMIT}`,
+      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${effectiveLimit}`,
     );
   }
   for (const skillId of coreSkillIds) {

package/src/manifest.ts

@@ -31,7 +31,10 @@ const targetSchema = z.object({
 }).strict();
 
 const manifestSchema = z.object({
-  core: z.object({ skills: z.array(skillIdSchema) }).strict(),
+  core: z.object({
+    skills: z.array(skillIdSchema),
+    limit: z.number().int().positive().optional(),
+  }).strict(),
   project: z.record(groupNameSchema, projectGroupSchema).optional(),
   targets: z.record(groupNameSchema, targetSchema).default({}),
 }).strict();
@@ -98,7 +101,10 @@ function tomlStringArray(values: string[]): string {
 
 /** Purpose-built serializer for this manifest's fixed shape — not a general TOML writer. */
 export function serializeManifest(manifest: Manifest): string {
-  const sections: string[] = [`[core]\nskills = ${tomlStringArray(manifest.core.skills)}`];
+  // An absent limit is left out rather than written as the default, so the file keeps saying
+  // "unset" and a future change to CORE_SKILL_LIMIT still reaches manifests that never opted in.
+  const coreLimit = manifest.core.limit === undefined ? "" : `\nlimit = ${manifest.core.limit}`;
+  const sections: string[] = [`[core]\nskills = ${tomlStringArray(manifest.core.skills)}${coreLimit}`];
 
   for (const [name, group] of Object.entries(manifest.project ?? {})) {
     sections.push(
@@ -140,14 +146,14 @@ export function pinCore(manifest: Manifest, skillId: string): Manifest {
   if (existing) {
     throw new Error(`skill "${skillId}" already pinned in ${existing}`);
   }
-  return { ...manifest, core: { skills: [...manifest.core.skills, skillId] } };
+  return { ...manifest, core: { ...manifest.core, skills: [...manifest.core.skills, skillId] } };
 }
 
 export function unpinCore(manifest: Manifest, skillId: string): Manifest {
   if (!manifest.core.skills.includes(skillId)) {
     throw new Error(`skill "${skillId}" is not pinned in [core]`);
   }
-  return { ...manifest, core: { skills: manifest.core.skills.filter((id) => id !== skillId) } };
+  return { ...manifest, core: { ...manifest.core, skills: manifest.core.skills.filter((id) => id !== skillId) } };
 }
 
 export function pinProject(manifest: Manifest, skillId: string, group: string, paths?: string[]): Manifest {
@@ -313,9 +319,10 @@ export function validateManifest(
   vaultPath: string,
   localVaultPaths: string[] = [],
 ): ManifestValidationResult {
-  if (manifest.core.skills.length > CORE_SKILL_LIMIT) {
+  const effectiveLimit = manifest.core.limit ?? CORE_SKILL_LIMIT;
+  if (manifest.core.skills.length > effectiveLimit) {
     throw new Error(
-      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${CORE_SKILL_LIMIT}`,
+      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${effectiveLimit}`,
     );
   }