dsh-skillflux

dsh-skillflux

Dynamic Skill Runtime Manager for DeepSeek Harness.

SkillFlux keeps the full Skill pool outside the model-facing catalog. For each task, it selects a small set of relevant Skills, mounts them for the current turn, and releases the mounts when the turn ends.

When the local pool has no good match, SkillFlux can search skills.sh and the public GitHub SKILL.md corpus live, then rank candidates with relevance-first quality and 30-day repository activity signals before proposing a pinned mount.

Status: v0.2 for DeepSeek Harness 0.1.1-rc.2. Harness is still a developer preview, so this project follows the current RC API.

中文文档

Why SkillFlux

A growing Skill library should not make every request carry a growing catalog. Large catalogs consume context and make Skill selection less predictable.

SkillFlux acts as a runtime layer between the Agent and its Skill pool. The automatic catalog contains no more than maxActiveSkills selected Skills (three by default), while the official DSH Skill Registry remains the source of truth. Explicit /skill-name invocations remain available separately.

Quick start

You need Node.js 22.20.0 or later and a DeepSeek Harness profile on the 0.1.1-rc.2 package line.

1. Install SkillFlux into the profile you use:

   dsh plugin --profile web add github:YiyuZh/dsh-skillflux
   

   Replace web with another profile name, such as headless, when needed.

2. Restart that Harness profile.

3. Verify the runtime from a DSH conversation:

   /skillflux status
   

For a reproducible deployment, pin a commit:

dsh plugin --profile web add github:YiyuZh/dsh-skillflux#<commit-sha>

The repository includes built lib/ artifacts, so GitHub installation doesn't run a prepare script. The bundle patch disables the official tool-skill consumer and mounts SkillFlux under the unique skillflux loader ID. It keeps the official skill Registry and skill-filesystem provider active.

How it works

User task
  -> ordered rules + deterministic lexical router (English and Chinese)
  -> optional usage-based tie-breaking and embedding fallback
  -> local Registry + persistent cache + adaptive online discovery
  -> relevance-first quality ranking with 30-day activity signals
  -> publish 1..maxActiveSkills metadata summaries through a Skill provider
  -> Registry skills mount eagerly; cached and remote bodies stay lazy
  -> Agent calls the `skill` tool for the exact listed name
  -> the provider downloads, verifies, and loads that body on demand
  -> turn/end releases the shortlist and provider catalog
  -> retain or prune downloaded files by age, size, and observed value

flowchart LR
  TASK["User task"] --> ROUTE["Route + discover<br/>(rules, lexical, adaptive online)"]
  ROUTE --> PUB["Publish metadata catalog<br/>(name + description only)"]
  PUB --> MODEL["Model sees available_skills"]
  MODEL -->|"calls skill &lt;name&gt;"| GET["Provider.get():<br/>download / verify / load"]
  GET --> BODY["Full SKILL.md body"]
  BODY --> ACT["Model follows the instructions"]
  ACT --> END["turn/end: release catalog"]

The model-facing catalog carries summaries only. A cached or remote body is downloaded, SHA-256 verified against its immutable commit, and loaded only when the model actually calls skill. Registry skills mount eagerly because their bodies are already local. Every published candidate is scoped to the receiving Agent; releasing a turn removes it from future catalogs without deleting cached files or text already stored in session history.

Capabilities

• Route by ordered rules, then deterministic English and Chinese lexical scores.
• Optionally use successful Skill loads as a small, decaying ranking boost for candidates that already pass the lexical relevance threshold.
• Optionally fill unmatched catalog slots with semantic similarity from a local Ollama or OpenAI-compatible embedding endpoint.
• Limit the model-facing catalog with maxActiveSkills.
• Optionally enforce a conservative estimated-token budget for the Skill catalog prompt.
• Discover candidates from the DSH Registry, the SkillFlux cache, skills.sh, and authenticated GitHub SKILL.md code search.
• Serve skills published over the MCP Skills extension (io.modelcontextprotocol/skills): a transport-agnostic client lists, validates, and content-binds skills from any registered MCP source under the same approval and trust boundaries, with a bundled zero-dependency stdio transport and a checked-in conformance smoke.
• Re-rank remote matches by task relevance, marketplace adoption, repository activity, stars, forks, license metadata, content provenance, and configured owner policy. Every result carries an explainable evidence level and warnings.
• Resolve remote candidates to immutable GitHub commit SHAs.
• Publish metadata-only summaries through one host-level Skill provider whose candidates resolve per Agent; cached and remote bodies load lazily on the skill call.
• Verify cached content with a SHA-256 manifest before every load.
• Adapt online discovery to local confidence: a confident local shortlist fills every catalog slot without network traffic, while partial local hits automatically fill the remaining slots from skills.sh and GitHub.
• Track per-source health with consecutive-failure cooldowns so a failing provider is skipped instead of retried every turn, and keep last-good catalogs through non-authoritative observations when discovery degrades.
• Record per-skill catalog-footprint and loaded-body token telemetry with a graceful fallback when the host token-meter service is absent; running token totals act as a deterministic eviction tie-break in installed-cache pruning.
• Ingest experimental federated ecosystem indexes, whose advisory official | verified | community | unreviewed tiers surface as evidence without ever granting trust.
• Automatically prune idle and low-value installed Skill cache entries while protecting active and in-flight mounts.
• Support per-remote-mount, per-repository/session, and automatic approval policies.
• Expose model tools for loading, searching, and mounting Skills.
• Expose /skillflux commands for status, routing explanations, usage, and cache cleanup.

Routing behavior

SkillFlux routes a task in this order:

1. Preserve an explicit user invocation such as /pdf-reader and exclude that name from automatic routing.
2. Group model-invocable Registry and cached candidates by Skill name. Registry entries represent a name first, while same-name cache entries remain available as fallbacks.
3. Apply matching routes in configuration order.
4. Score the remaining name representatives with deterministic lexical matching and reject scores below minRouteScore.
5. When adaptiveRouting is enabled, add a bounded, time-decaying usage boost only to candidates that already passed minRouteScore. Rules keep priority, and history cannot make an irrelevant candidate cross the threshold.
6. In hybrid mode, use embeddings only when rules and lexical matching leave catalog slots unfilled. Semantic results never displace those earlier matches.
7. Publish the selected names until maxActiveSkills is reached. Registry names mount eagerly; cached and remote names stay metadata-only and their bodies load lazily when the model calls skill. When catalogTokenBudget is enabled, skip a candidate that would make the estimated catalog prompt exceed that budget. A lazy load that fails tries its same-name fallbacks in candidate-pool order under one shared install deadline.

The lexical score is:

For equal scores, Registry candidates rank before cached candidates, and cached candidates rank before remote candidates. Cache ties prefer higher install counts and then a stable source/name order.

Semantic fallback uses cosine similarity, filters results below minEmbeddingSimilarity, and reports a rounded 0-100 score. It runs only after the ordered rule and lexical stages.

Online quality discovery

Remote discovery is live, not a bundled catalog:

1. skills.sh supplies marketplace matches and install counts.
2. When GITHUB_TOKEN or GH_TOKEN is available, GitHub Code Search finds matching public SKILL.md files outside the marketplace. SkillFlux fetches and validates each matched frontmatter before accepting it.
3. GitHub repository metadata supplies the immutable HEAD commit, stars, forks, license, archive state, owner type, and last push time.
4. SkillFlux rejects zero-relevance, archived, disabled, below-star, and below-quality candidates, then applies the configured evidence policy.
5. Exact duplicate candidate identities are collapsed. Equal root SKILL.md hashes in different repositories remain separate because adjacent resources may differ; they are not treated as independent provider corroboration.

The quality score is capped at 100. Relevance is a gate and the largest single component, so a famous but unrelated repository cannot outrank an exact new match merely because it has more stars.

remoteRecentActivityDays defaults to 30. Activity inside that window receives the full freshness contribution; older maintained projects decay gradually instead of being discarded. Add owners you have independently vetted to remoteTrustedOwners; being an organization or having many stars is not itself treated as verification.

Each candidate is labeled unverified, community, corroborated, or trusted. The default remoteTrustPolicy: community accepts a directly previewed and content-pinned GitHub Skill even when it is new and has few stars, but exposes low-adoption, missing-license, stale-activity, and source-coverage warnings. corroborated requires both a pinned content preview and discovery by multiple providers. trusted means only that the repository owner appears in your explicit remoteTrustedOwners list; it is not a security certification. Use remoteBlockedOwners for an explicit deny list. An owner cannot be both trusted and blocked.

These controls are re-applied to installed SkillFlux cache entries on every search, automatic route, and mount. Removing an owner from remoteTrustedOwners therefore revokes its stored trusted label; adding it to remoteBlockedOwners prevents reuse after a restart. Legacy cache manifests without an evidence label are treated as community because their immutable commit and installed-directory hash are known, but they do not satisfy corroborated or trusted policies.

GitHub code search requires authentication. Start DSH from a shell that exposes one of the standard variables, for example in PowerShell:

$env:GH_TOKEN = gh auth token
dsh web

Without a token, SkillFlux continues to search skills.sh and enrich those results through the public GitHub REST API. It simply skips the broader GitHub code-search provider.

Discovery result cache

Successful online searches are cached across DSH restarts. The default five- minute TTL avoids repeated marketplace and GitHub API calls for the same task. After the TTL, SkillFlux queries the providers again. If that refresh fails, it may reuse the prior immutable candidates for an additional 24 hours; an explicit caller cancellation never falls back to stale data.

The cache key is a SHA-256 fingerprint of the bounded normalized query and the active discovery/ranking configuration. User task text, tokens, and Skill bodies are not persisted. Candidate metadata remains pinned to the commit originally validated, so stale fallback affects ranking freshness rather than source integrity or approval identity.

The evidence-aware cache document is versioned. Older ranking-cache formats are discarded and rebuilt online instead of being interpreted under newer trust semantics.

The cache is stored atomically at $DSH_HOME/storages/skillflux/remote-discovery.json, limited to 100 entries by default, and hard-capped at 4 MiB. Set remoteCacheTtlMs: 0 to disable it.

Adaptive online discovery

With remoteDiscovery: automatic, SkillFlux only goes online when it needs to. A confident local shortlist that fills every catalog slot skips remote traffic entirely. When local routing leaves slots unfilled or finds nothing, SkillFlux searches skills.sh and GitHub to fill the remaining slots up to maxActiveSkills and remoteAutoMountLimit.

Each provider carries health state. After remoteHealthFailureThreshold consecutive failures a source enters a remoteHealthCooldownMs cooldown and is skipped, so an outage degrades to the healthy sources plus the discovery cache instead of being retried on every turn. A successful call clears the source's failure history. When discovery degrades or falls back to stale cached candidates, the published catalog is marked non-authoritative; the registry keeps its last-good catalog while the still-usable candidates remain visible. /skillflux status reports failure counts and degraded state per provider.

Installed Skill cache governance

Downloaded Skills live separately under $DSH_HOME/cache/skillflux. After a remote Skill mounts successfully, SkillFlux evaluates this installed cache and checks it again after that session's turn releases its mounts. It removes entries that have been idle for 90 days by default. If the remaining pool still exceeds 100 entries or 512 MiB, it evicts the lowest-value entries first using successful Skill tool uses, mounts, last activity, quality score, and adoption as deterministic evidence.

Usage from the initial remote candidate and later cached candidate is aggregated by immutable cache ID. This joins their changing candidate IDs without sharing value between different commits of the same Skill. Legacy records without a cache ID apply only to the newest matching repository/Skill version. Updates to the shared usage file are locked and merged across Harness processes. Active mounts and concurrent cache loads are protected across Service instances and Harness processes that share a DSH_HOME. Lease heartbeats bound orphan-marker retention if a crashed process ID is reused, while a process-local live-lease registry lets hot-reloaded Service instances reclaim retired markers. Automatic governance failures only log a warning; a compromised coordination lock fails the current cache operation instead of continuing without mutual exclusion.

Run /skillflux cache prune to apply the same policy immediately. Set cacheAutoPrune: false to disable automatic runs, or cacheMaxIdleDays: 0 to disable age-based eviction while retaining entry and byte limits. When usageTracking is off, governance conservatively falls back to installation time and immutable discovery metadata because no local usage evidence exists. Directories with an invalid manifest are excluded from automatic deletion, reported by /skillflux status, and can be removed explicitly with /skillflux cache clean all.

Configuration

SkillFlux accepts these plugin options:

maxActiveSkills: 3
minRouteScore: 8
approvalPolicy: always       # always | session | automatic; gates lazy remote activation and explicit mounts
remoteDiscovery: automatic   # automatic (adaptive) | on-demand | off
remoteProviders: [skills.sh, github]
remoteSearchLimit: 5
remoteAutoMountLimit: 3      # max remote candidates published for lazy activation; 1 disables fallback
remoteSearchTimeoutMs: 30000
remoteMinQualityScore: 35     # 0-100
remoteMinStars: 0
remoteRecentActivityDays: 30
remoteTrustPolicy: community  # open | community | corroborated | trusted
remoteTrustedOwners: []       # e.g. [anthropics, openai, vercel-labs]
remoteBlockedOwners: []
remoteCacheTtlMs: 300000                  # 0 disables
remoteCacheStaleIfErrorMs: 86400000       # additional stale window
remoteCacheMaxEntries: 100
remoteHealthFailureThreshold: 3           # consecutive failures before a source is degraded
remoteHealthCooldownMs: 60000             # degraded source skip window
cacheAutoPrune: true
cacheMaxEntries: 100
cacheMaxTotalBytes: 536870912              # 512 MiB across installed Skills
cacheMaxIdleDays: 90                       # 0 disables idle eviction
catalogDescriptionMaxLength: 160
catalogTokenBudget: 0              # 0 disables; otherwise 64-1000000
maxSkillFiles: 1000
maxSkillBytes: 10485760
installTimeoutMs: 300000
routerMode: lexical                # lexical | hybrid
embeddingProvider: ollama          # ollama | openai-compatible
embeddingEndpoint: http://127.0.0.1:11434/api/embed
embeddingModel: embeddinggemma
embeddingApiKeyEnv: SKILLFLUX_EMBEDDING_API_KEY
embeddingTimeoutMs: 5000
embeddingCandidateLimit: 128
embeddingCacheSize: 512
minEmbeddingSimilarity: 0.45
usageTracking: true
usageMaxEntries: 1000
adaptiveRouting: false
adaptiveMaxBoost: 6
adaptiveMinUses: 2
adaptiveHalfLifeDays: 30
mcpDiscovery: automatic        # automatic | off; gates registered MCP Skills sources
mcpTrustedServers: []          # host-assigned labels allowed trusted evidence
mcpBlockedServers: []          # host-assigned labels whose skills are always refused
registryDiscovery: off         # off | automatic; experimental federated index ingestion
routes: []

Add ordered rules when a known task must prefer specific Skills:

routes:
  - matchAll: [pdf, analyze]
    skills: [pdf-reader, document-parser]
  - matchAny: [react, frontend]
    skills: [react-specialist]

A rule can contain matchAll, matchAny, or both. Rule results keep their declared order, skip unavailable Skills, and still respect maxActiveSkills.

Hybrid embedding router

Embedding routing is opt-in. The recommended private setup uses Ollama:

ollama pull embeddinggemma

routerMode: hybrid
embeddingProvider: ollama
embeddingEndpoint: http://127.0.0.1:11434/api/embed
embeddingModel: embeddinggemma

For an OpenAI-compatible embedding service, select the protocol and point at its exact embeddings endpoint:

routerMode: hybrid
embeddingProvider: openai-compatible
embeddingEndpoint: https://provider.example/v1/embeddings
embeddingModel: provider-embedding-model
embeddingApiKeyEnv: SKILLFLUX_EMBEDDING_API_KEY

Set the named environment variable in the process that launches DSH. SkillFlux never stores that value. Candidate vectors are kept in a bounded in-memory LRU and disappear when the plugin stops. An unavailable, malformed, timed-out, or reconfigured embedding endpoint fails open to the lexical result.

Usage statistics and adaptive routing

Usage tracking records successful mounts and successful skill({ name }) loads by exact candidate ID. It is enabled by default, while adaptive routing is opt-in:

usageTracking: true
adaptiveRouting: true
adaptiveMaxBoost: 6
adaptiveMinUses: 2
adaptiveHalfLifeDays: 30

Records are stored atomically in $DSH_HOME/storages/skillflux/usage.json (normally ~/.dsh/storages/skillflux/usage.json) and bounded by usageMaxEntries. The file also has a hard 2 MiB limit; least-recently-useful records are evicted first when either bound is reached. SkillFlux stores only the candidate ID, Skill name, origin, source, counters, token counts, and timestamps. It does not store task text, Skill instructions, or resources.

The boost is capped by adaptiveMaxBoost, requires at least adaptiveMinUses successful loads, and halves after adaptiveHalfLifeDays without use. A telemetry read or write failure falls open to normal routing. Set usageTracking: false to disable persistence; in that case adaptiveRouting must also remain false.

Token telemetry

When the host mounts the DSH token-meter service, SkillFlux prices the catalog entry lines and each loaded SKILL.md body with the native estimator. When the service is absent, it falls back to the same portable estimate the catalog budget uses (ceil(UTF-8 bytes / 3)). No package dependency is added for this: the optional ctx.tokenMeter service is resolved at runtime and any failure degrades silently to the portable estimate.

Per-skill token counts are appended to the usage records and shown by /skillflux status and /skillflux usage: the catalog footprint at the last mount, the loaded-body tokens at the last load, and their running total, plus which estimator produced them. Only token counts are persisted; task text, Skill instructions, and resources never reach usage.json. When two installed cache versions are otherwise identical on recency, uses, and mounts, pruning evicts the higher running body-token version first; the ordering is deterministic and absent evidence leaves the historical order unchanged. Token telemetry never changes routing or approval decisions.

Catalog context budget

catalogTokenBudget is an optional second bound in addition to maxActiveSkills. The default 0 keeps existing behavior. A nonzero value preflights each mount and rejects only the candidate that would exceed the budget, allowing later smaller or same-name fallback candidates to continue:

maxActiveSkills: 3
catalogDescriptionMaxLength: 160
catalogTokenBudget: 512

The estimate covers the complete replacement-form Skill catalog prompt after description truncation. It uses ceil(UTF-8 bytes / 3): intentionally conservative for typical English and close to one token per CJK character, but it is not a model-specific tokenizer result. /skillflux status reports the current estimate and /skillflux explain marks rejected candidates as budget-skipped.

Approval policies

If approval is unavailable, rejected, or canceled, the remote mount fails closed.

Automatic remote fallback

With approvalPolicy: automatic, a broken first result no longer blocks a usable second result. SkillFlux tries at most remoteAutoMountLimit candidates in discovery order (default 3, allowed 1–5), stopping after the first successful mount. Set it to 1 for single-candidate behavior.

All attempts share one installTimeoutMs deadline, starting after discovery. The next candidate is not started after this deadline, explicit cancellation, or turn cleanup. In-flight lock acquisition and cleanup are awaited safely; the deadline is not a strict wall-clock bound on their completion.

Every attempt still enforces current trust/owner policy, pinned-source verification, installed-content integrity, and catalog limits. /skillflux explain records mount-failed, mount-timeout, budget-skipped, or mounted. Failed candidates are removed from this turn's hint; unattempted candidates remain available. A new skillflux_search can retry a failure; failures are not persisted as a blacklist. always, session, and explicit skillflux_mount keep their existing approval behavior and never silently switch candidates.

MCP Skills sources