How Credentials Are Managed in Dolshoi Credential Mode for k-skill

k-skill manages credentials in Dolshoi Credential Mode by detecting the DOLSHOI_ACTION_BROKER_URL environment variable and the vault-run capability, then retrieving secrets through the Dolshoi vault with automatic UI prompts for missing credentials.

The k-skill repository (NomaDamas/k-skill) implements a dual-mode credential management system designed to protect sensitive data when running inside Dolshoi execution environments. When operating in Dolshoi Credential Mode, the runtime treats API keys, passwords, and other secrets as opaque vault credentials rather than plain environment variables. Understanding how credentials are managed in Dolshoi Credential Mode is essential for developers who need to prevent credential leakage in logs or chat histories while maintaining portability for local development.

Detecting Dolshoi Credential Mode

The runtime determines activation based on two mandatory conditions evaluated at startup. Both must be present simultaneously to trigger vault-based credential management according to the rules defined in AGENTS.md.

Environment Variable Detection

The runtime checks for the presence of DOLSHOI_ACTION_BROKER_URL in the process environment. This variable signals that the skill is executing within a Dolshoi-managed context where a credential broker is available to handle secret provisioning.

Capability Verification

The runtime verifies that the execution environment exposes the vault-run capability. This capability provides the secure interface necessary to communicate with the Dolshoi vault infrastructure and fetch encrypted credentials.

Retrieving Vault Credentials

Once Dolshoi Credential Mode is active, all secret requests route through the vault system using specific runtime functions that enforce security boundaries.

Primary Retrieval via vault-run

Skills invoke the vault-run capability to fetch credentials by specifying the service identifier and secret key. The runtime returns an opaque credential object that masks the underlying value, preventing accidental exposure through logging or console output.

Handling Missing Credentials with request_vault_credential

When a requested credential is not provisioned in the vault, the runtime calls the request_vault_credential helper function. This function opens a secure UI within the Dolshoi vault interface, allowing users or automated processes to supply the missing value. After provisioning completes, the skill retries the vault-run fetch to obtain the newly stored secret.

Security Guarantees

The framework enforces strict security boundaries to prevent credential exposure throughout the skill lifecycle.

Opaque Credential Handling

Secrets remain encrypted and opaque throughout execution. The runtime passes credentials directly to the skill implementation without printing, logging, or storing them in chat histories. The implementation receives only a sealed token suitable for API authentication headers.

Isolation from Environment Variables

Unlike generic mode, Dolshoi Credential Mode never exposes secrets through standard environment variables. This eliminates risks of credential leakage through process inspection, shell history, or environment dumps.

Generic Fallback Mode

When either the DOLSHOI_ACTION_BROKER_URL variable or the vault-run capability is absent, the runtime automatically switches to generic credential management.

Environment Variable Convention

In fallback mode, skills read secrets from prefixed environment variables such as KSKILL_MY_SERVICE_KEY. Developers must explicitly export these variables before invoking the skill.

Host-Level Vault Files

As a secondary fallback mechanism, the runtime may read from host-level vault files stored on the local filesystem, depending on the specific skill configuration documented in individual instruction files.

Implementation Reference

The credential management logic is documented and validated across several key files in the repository:

• AGENTS.md — Defines the exact detection logic requiring both DOLSHOI_ACTION_BROKER_URL and the vault-run capability to activate Dolshoi Credential Mode.
• srt-booking/instruction.md — Demonstrates skill-specific implementation patterns using vault-run and request_vault_credential for the SRT booking skill.
• packages/k-skill-cli/test/snapshots/srt-booking.dolshoi.md — Contains test snapshots validating the detection logic and credential retrieval flow in Dolshoi mode.
• packages/k-skill-cli/test/snapshots/srt-booking.generic.md — Provides test coverage for the generic fallback path when Dolshoi mode is inactive.

Code Example

The following pattern from the k-skill test snapshots illustrates the dual-mode credential retrieval logic:

// Pattern from k-skill test snapshots
if (process.env.DOLSHOI_ACTION_BROKER_URL && hasCapability('vault-run')) {
  // Dolshoi Credential Mode – try to fetch the credential from the vault
  const cred = await vaultRun('my-service', 'my-secret-key');
  if (!cred) {
    // Credential not provisioned → ask the Dolshoi UI to provide it
    await request_vault_credential('my-service', 'my-secret-key');
    // After the UI completes, retry fetching the credential
    const cred = await vaultRun('my-service', 'my-secret-key');
  }
  // Use the credential (e.g., for an API call) without ever exposing it
  await callExternalApi({ apiKey: cred });
} else {
  // Generic fallback – read from env vars or host vault
  const cred = process.env.KSKILL_MY_SERVICE_KEY;
  await callExternalApi({ apiKey: cred });
}

Summary

• Dolshoi Credential Mode activates only when both DOLSHOI_ACTION_BROKER_URL and the vault-run capability are present.
• Secrets are retrieved via the vault-run capability and remain opaque to prevent logging or chat exposure.
• Missing credentials trigger request_vault_credential to open the Dolshoi vault UI for secure provisioning.
• When Dolshoi mode is unavailable, skills automatically fall back to KSKILL_-prefixed environment variables or host-level vault files.
• Security rules are enforced according to AGENTS.md and validated through test snapshots in packages/k-skill-cli/test/snapshots/.

Frequently Asked Questions

What triggers Dolshoi Credential Mode in k-skill?

Dolshoi Credential Mode activates when the runtime detects the DOLSHOI_ACTION_BROKER_URL environment variable and confirms the vault-run capability is available in the execution environment. Both conditions must be satisfied simultaneously according to the logic defined in AGENTS.md.

How does k-skill handle credentials that are not yet provisioned in the vault?

When a credential is missing from the vault, the runtime invokes request_vault_credential to open a secure UI prompt within the Dolshoi interface. This allows users or automation to supply the secret, after which the skill retries the vault-run call to retrieve the newly stored value.

Are credentials ever exposed in logs or chat when using Dolshoi Credential Mode?

No. The k-skill framework guarantees that secrets remain opaque objects never printed to stdout, written to log files, or stored in chat histories. The runtime passes credentials directly to the skill implementation as sealed tokens suitable only for API authentication.

What happens if I run a k-skill outside the Dolshoi environment?

Skills automatically fall back to generic credential mode, reading secrets from standard environment variables prefixed with KSKILL_ (such as KSKILL_MY_SERVICE_KEY) or from host-level vault files. This dual-mode design ensures portability across different execution environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}