zeroclaw-labs/zeroclaw · error · anyhow::Error

cli-skills-agent-not-configured

cli-skills-agent-not-configured

Error message

agent '{$alias}' is not configured

What it means

`skills list --agent <alias>` mirrors exactly what one agent loads at runtime, so it first verifies the alias exists under [agents] in the config. config.agent(alias) returning None means no agent with that alias is configured, and the command bails with the cli-skills-agent-not-configured message before loading any skills. Note the bundle branch runs first: this error fires only when --bundle is not given.

Source

Thrown at src/skills/mod.rs:86

            let mut skipped: Vec<DroppedSkill> = Vec::new();
            if let Some(ref b) = bundle {
                // A single bundle's on-disk skills.
                let dir =
                    zeroclaw_config::skill_bundles::resolve_directory(config, &install_root, b)
                        .map_err(anyhow::Error::msg)?;
                rendered.push((
                    get_required_cli_string_with_args(
                        "cli-skills-list-group-bundle",
                        &[("alias", b)],
                    ),
                    load_skills_from_directory(&dir, allow_scripts).0,
                ));
            } else if let Some(ref a) = agent {
                // Exactly what this agent loads at runtime — the same loader the
                // agent boot/loop uses (workspace + open-skills + plugins +
                // assigned bundles), so `list --agent` mirrors runtime behavior.
                if config.agent(a).is_none() {
                    anyhow::bail!(
                        "{}",
                        get_required_cli_string_with_args(
                            "cli-skills-agent-not-configured",
                            &[("alias", a)],
                        )
                    );
                }
                let (skills, dropped, _shadowed) =
                    load_skills_for_agent_from_config_audited(config, a);
                skipped.extend(dropped);
                rendered.push((
                    get_required_cli_string_with_args(
                        "cli-skills-list-group-agent",
                        &[("alias", a)],
                    ),
                    skills,
                ));
            } else {

View on GitHub (pinned to 88bb9c8533)

Solutions

  1. Check the exact alias spelling and case against the [agents] table of the active config
  2. Run `skills list` with no --agent — it needs no agent and shows the full inventory
  3. If the agent should exist, add it under [agents.<alias>] or fix the config path/env var pointing at the wrong file
  4. Copy-paste the alias from the config instead of retyping it

Example fix

# before
zeroclaw skills list --agent helpr

# after
zeroclaw skills list --agent helper
Defensive patterns

Strategy: validation

Validate before calling

// Before `skills list --agent <alias>`
if config.agent(alias).is_none() {
    eprintln!("unknown agent '{alias}'; configured agents: {:?}",
              config.agents.keys().collect::<Vec<_>>());
    return;
}

Try / catch

if let Err(e) = handle_command(SkillCommands::List { agent: Some(alias), bundle: None }, &config).await {
    if e.to_string().contains("is not configured") { /* alias problem: suggest configured agents, no retry */ }
}

Prevention

When it happens

Trigger: Running `skills list --agent <typo>`; the agent was renamed or deleted from the config after the command was scripted; the config file actually loaded (env override, different data dir) does not contain the agent.

Common situations: Typos and case mismatches (Helper vs helper); stale scripts or docs referencing an old alias; user-level vs project-level config split so the agent lives in the other file.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/b196ec5db4630b29. Report an issue: GitHub.