zylon-ai/private-gpt · error · ValueError

Skill management tools require a SkillArtifact in the tool c

Error message

Skill management tools require a SkillArtifact in the tool context.

What it means

Raised by the SkillManagementProcessor's _make_builder when a skill management tool (e.g. skill list) is being resolved but its tool context contains no SkillArtifact. The builder needs the artifact's skill_filter to construct SkillManagementToolBuilder, so the request fails.

Source

Thrown at private_gpt/components/tools/processors/skill_management_processor.py:108

                built_any |= _replace_tool(
                    request,
                    tool,
                    [
                        builder.build_list_skills(
                            name=tool.name or SKILL_LIST_TOOL_NAME,
                            type=tool.type or SKILL_LIST_TOOL_NAME + "_v1",
                        )
                    ],
                )
        return built_any

    def _make_builder(
        self, request: ResolvedChatRequest, tool: Any
    ) -> SkillManagementToolBuilder:
        tool_context = _get_tool_context(request, tool)
        skill_artifacts = [a for a in tool_context if isinstance(a, SkillArtifact)]
        if not skill_artifacts:
            raise ValueError(
                "Skill management tools require a SkillArtifact in the tool context."
            )
        if len(skill_artifacts) > 1:
            raise ValueError(
                "Only one SkillArtifact is supported per skill management tool."
            )
        return SkillManagementToolBuilder(
            skill_service=self._skill_service,
            skill_filter=skill_artifacts[0].skill_filter,
            skill_injection_mode=self._settings.skills.skill_injection_mode,
        )

View on GitHub (pinned to 4a030776a3)

Solutions

Attach exactly one SkillArtifact (with skill_filter) to the skill management tool's context
Or remove skill management tools from the request when no skill scope applies
Check the skills settings (settings.skills) are configured and the skill service is available

Example fix

# before
tools=[ToolConfig(name=SKILL_LIST_TOOL_NAME)]
# after
tools=[
    ToolConfig(
        name=SKILL_LIST_TOOL_NAME,
        context=[SkillArtifact(skill_filter=SkillFilter(...))],
    )
]

Defensive patterns

Strategy: validation

Validate before calling

skills = [a for a in (tool_context or []) if isinstance(a, SkillArtifact)]
if not skills:
    # remove skill management tools from the request or attach a SkillArtifact

Type guard

def is_skill_artifact(ctx: object) -> bool:
    return isinstance(ctx, SkillArtifact)

Try / catch

try:
    resp = await client.chat(request)
except ValueError as e:
    if "require a SkillArtifact" in str(e):
        # attach SkillArtifact(skill_filter=...) and resend
        raise

Prevention

Only expose skill management tools when a skill scope has been chosen
Validate tool/artifact pairings client-side with a shared schema
Test skill tool requests in CI with a minimal SkillArtifact fixture

When it happens

Trigger: Including a skill management tool (SKILL_LIST_TOOL_NAME or siblings) in tool_config.tools while its tool_context is empty or holds only non-skill artifacts.

Common situations: Enabling skill tools globally without scoping them to a skill set; attaching the SkillArtifact to another tool entry in a multi-tool request; skills subsystem disabled but the tool still requested.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/bb71b8c6952f9c0d. Report an issue: GitHub.