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

> Learn how k-skill manages credentials in Dolshoi Credential Mode. Discover automatic secret retrieval via the Dolshoi vault and UI prompts for missing information.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```typescript
// 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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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.