agent-kernel: Skill for Claude Code

Adding a New Secret Provider

This guide walks through adding a built-in provider to the secret-resolution capability (ak-py/src/agentkernel/secret/). Use AWSSMSecretProvider (ak-py/src/agentkernel/secret/providers/aws_ssm.py) as the reference implementation, since it is the only built-in that talks to a remote store. The ak-dev-architecture skill's Secret Resolution section covers the manager, cache and resolution order this guide builds on.

Existing Providers

Do You Need a Built-in?

A dotted path already lets a user plug in any SecretProvider subclass with no core change: resolve_dotted(..., base=SecretProvider) imports it and calls its create. AWS Secrets Manager ships this way in v1 (see docs/specs/749-secret-resolution/design.md, Non-goals). Add a built-in only when the backend is broadly useful, has a stable SDK, and deserves a short name, tested IAM wiring and docs. Otherwise, document the dotted-path route in docs/docs/advanced/secrets.md (Custom providers) and stop there.

The Contract

SecretProvider (secret/base.py) is small. The rules around it are what matter:

• get_secret(key) -> str | None: return the stored value, or None when the backend does not hold it. A miss is not an error. Raise SecretError (secret/errors.py) only when the backend failed (credentials, network, throttling, authorization), and never put the value in the message.
• The provider owns its addressing. key is always an environment-variable-style name (^[A-Z][A-Z0-9_]*$, e.g. OPENAI_API_KEY). Translating it to the backend's name (path, secret id, lowercase) happens here and nowhere else. The manager transforms nothing.
• Never cache and never fall back. SecretManager owns the environment → cache → provider order and SecretCache owns TTLs. A provider that caches breaks invalidate() and rotation.
• Tolerate concurrent calls. The manager calls the provider outside any lock, and concurrent cold reads may each call it. Create SDK clients lazily behind a lock (the double-checked client property in aws_ssm.py).
• Return values verbatim. Don't strip whitespace or parse JSON, because values are flat strings. Treat an empty value as absent (EnvSecretProvider returns os.environ.get(key) or None).
• create(cls, config: _SecretConfig) receives the whole secret block, not just secret.provider, so the deployment-wide secret.prefix is shared by every backend. Validate settings here and raise AKConfigError (core/util/factory.py) on unusable values, the way AWSSMSecretProvider._normalize_prefix rejects an empty or nested prefix. It fires at the first SecretManager.current(), so misconfiguration fails at startup, not on first read.