docs(skill): add library-workflow reference for the Python facade - #419
Conversation
New references/library-workflow.md documents `from keboola_agent_cli import Client` -- in-process query + Storage Files, the string-typing gotcha, auth, branch scoping, FileEntry shape, and when-not-to-use. Linked from the SKILL.md Workflow references table (manual section; the auto-generated command table is untouched).
| | **Agent Tasks via REST** (`kbagent http <verb> /agents...` from inside scheduled subprocesses; SSE streaming) | [agent-tasks-rest-workflow](references/agent-tasks-rest-workflow.md) | | ||
| | **Data apps** (create / deploy / start / stop / password / delete; the §9 redeploy contract) | [data-app-workflow](references/data-app-workflow.md) | | ||
| | Storage Files (upload, download, tags, load/unload) | [storage-files-workflow](references/storage-files-workflow.md) | | ||
| | **Python library** (`from keboola_agent_cli import Client` -- in-process query + Storage Files, no CLI/daemon/config-dir) | [library-workflow](references/library-workflow.md) | |
There was a problem hiding this comment.
🟡 Missing SKILL.md description trigger keywords for the new Python library topic area
The CONTRIBUTING.md mandates: "update the description: trigger keywords when introducing a new topic area (so description-matching auto-triggers the skill)". The Python library facade (from keboola_agent_cli import Client) is a new topic area, but the SKILL.md description: block (plugins/kbagent/skills/kbagent/SKILL.md:4-68) was not updated with relevant trigger keywords. Without keywords like python library, keboola_agent_cli, import Client, in-process query, Client facade, library workflow, etc., the skill will not auto-trigger when a user asks about using the Python library programmatically. The workflow row was correctly added to the table (line 412), but the description triggers were missed.
Prompt for agents
The SKILL.md description block (lines 4-68, inside the YAML frontmatter) needs trigger keywords added for the new Python library topic area. Add keywords like: python library, keboola_agent_cli, import Client, from keboola_agent_cli import Client, in-process query, library facade, Client facade, Files facade, FileEntry, stateless library, no CLI subprocess, no daemon to the description field in the YAML frontmatter. These should be added in the Triggers: section (around line 13-68) so that description-matching auto-triggers the skill when users ask about the Python library. This is a mandatory CONTRIBUTING.md requirement under 'Documentation changes (mandatory!)' > SKILL.md non-table portions.
Was this helpful? React with 👍 or 👎 to provide feedback.
Why
The library facade (#416, 0.61.0/0.61.1) had docs scattered across the README,
lib.pydocstrings,gotchas.md, and the keboola-expert matrix — but no dedicated reference workflow doc like every other kbagent surface (storage-files, workspace, sync, ...). Asked: "where's the guide for using kbagent as a Python library?"What
New
plugins/kbagent/skills/kbagent/references/library-workflow.md— a single guide forfrom keboola_agent_cli import Client:Client,query,files.*,raw,FileEntry).query()with the string-typing gotcha front and center (Snowflake returns strings; cast caller-side), plus the UPPERCASE-folding, truncation-warning, and provisioned-workspace facts.read_bytes,list,delete; theFileEntryshape; the deliberateread_bytes-over-signed-url design).Client.rawescape hatch.servefor an HTTP API).Linked from the SKILL.md Workflow references table. The auto-generated command table (between the
BEGIN/END AUTO-GENERATED COMMANDSmarkers) is untouched.Tests
make skill-checkgreen (SKILL.md is up-to-date),format-checkgreen. Documentation-only — no version bump, no changelog (plugin skill content, not a CLI code release).