feat(agent): build skills (#4918)#4924
Conversation
Implements Part B of the agent-skills design: adds three new platform build skills as SDK SkillTemplate constants and registers them in the static workflow catalog under reserved __ag__ slugs. - build-your-first-app (__ag__build_your_first_app): the orchestrator skill - discover-and-wire-tools (__ag__discover_and_wire_tools): promoted draft with the section-3.3 edits (instructions.agents_md, self-modify via commit_revision instead of the curl create skill) - set-up-triggers (__ag__set_up_triggers): cron + event trigger skill Single-sources agenta-getting-started by dropping the stale, never-loaded on-disk copy at services/agent/skills/agenta-getting-started/SKILL.md; the SDK constant remains the one canonical source. Includes the #4918 design doc under docs/design/agent-workflows/projects/agent-skills/. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Review needed (draft, do not merge yet). Specifically:
Open questions from the design (sections 7–8) intentionally left undecided here: whether to fold |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 756df440-3956-46c8-86b2-8a8cb936bb43
📒 Files selected for processing (5)
api/oss/src/core/workflows/static_catalog.pydocs/design/agent-workflows/projects/agent-skills/design.mddocs/design/agent-workflows/projects/agent-skills/status.mdsdks/python/agenta/sdk/agents/adapters/agenta_builtins.pyservices/agent/skills/agenta-getting-started/SKILL.md
💤 Files with no reviewable changes (1)
- services/agent/skills/agenta-getting-started/SKILL.md
| BUILD_YOUR_FIRST_APP_SLUG: { | ||
| "latest": "v1", | ||
| "versions": { | ||
| "v1": _skill_revision(BUILD_YOUR_FIRST_APP_SKILL), | ||
| }, | ||
| }, | ||
| DISCOVER_AND_WIRE_TOOLS_SLUG: { | ||
| "latest": "v1", | ||
| "versions": { | ||
| "v1": _skill_revision(DISCOVER_AND_WIRE_TOOLS_SKILL), | ||
| }, | ||
| }, | ||
| SET_UP_TRIGGERS_SLUG: { | ||
| "latest": "v1", | ||
| "versions": { | ||
| "v1": _skill_revision(SET_UP_TRIGGERS_SKILL), | ||
| }, | ||
| }, |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
These slugs go live before the required tools exist.
The new entries make __ag__build_your_first_app, __ag__discover_and_wire_tools, and __ag__set_up_triggers resolvable through the static namespace immediately. Their bodies and the accompanying design/status docs still describe missing builder-capability tools (find_capabilities, find_triggers, create_schedule, create_subscription, etc.), so embedding them now publishes skills the runtime cannot actually complete. Gate catalog registration until those tool contracts land, or keep them out of the live static namespace for this draft.
| Status: rewrite for Mahmoud's review. Grounded in code on `gitbutler/edit` over `big-agents`, | ||
| 2026-06-28. Paths are absolute. This replaces the first draft, which mixed the product question | ||
| (which skills do we need) with the implementation question (how a skill reaches the agent) and | ||
| read as unreviewable. This version separates the two and leads with the answer. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Avoid machine-local absolute paths in repo docs.
The /home/mahmoud/... convention introduced here will not resolve for anyone else or in rendered docs. Please switch these references to repo-relative paths.
| The skill lives in two places, and they have diverged. | ||
|
|
||
| - The canonical content is an SDK constant, `GETTING_STARTED_WITH_AGENTA_SKILL`, at | ||
| `/home/mahmoud/code/agenta/sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py:93`. The | ||
| static catalog imports it and serves it under the reserved slug | ||
| `__ag__getting_started_with_agenta` | ||
| (`/home/mahmoud/code/agenta/api/oss/src/core/workflows/static_catalog.py:82`). This constant is | ||
| the only copy the running agent ever sees. | ||
| - A second copy is a file at | ||
| `/home/mahmoud/code/agenta/services/agent/skills/agenta-getting-started/SKILL.md`. Its text | ||
| differs from the constant, and the runner never reads it. The runner composes each SKILL.md | ||
| from the wire skill it receives, keyed by name, and writes that into the sandbox | ||
| (`/home/mahmoud/code/agenta/services/agent/src/engines/skills.ts:148`). The on-disk directory | ||
| is an authoring artifact that has gone stale. | ||
|
|
||
| So the file misleads any human who reads it, because it is not what the agent runs. Single-source | ||
| the body. The constant stays canonical. Section 7 asks how: generate the file from the constant, | ||
| assert the file against the constant in a test, or drop the file. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Update the single-source section to match this PR.
Lines 171-188 and 474-477 still describe services/agent/skills/agenta-getting-started/SKILL.md as present and leave its removal open, but this branch already deletes that file and makes the SDK constant the only shipped source. The design doc should reflect the decided state, not the pre-change discussion.
Also applies to: 474-477
🧰 Tools
🪛 LanguageTool
[grammar] ~173-~173: Ensure spelling is correct
Context: ...GETTING_STARTED_WITH_AGENTA_SKILL, at /home/mahmoud/code/agenta/sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py:93. The static catalog imports it and ser...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
| Research done. Design rewritten after Mahmoud judged the first draft unreviewable. Nothing built. | ||
| This is docs-first. The placeholder skill bodies live inside `design.md` as artifacts, not as real | ||
| skill files yet. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
This status doc is already stale within the same PR.
The branch adds three builtin SkillTemplates, registers them in the static catalog, and removes the stale on-disk agenta-getting-started copy, so "Nothing built" and the single-sourcing bullet in the open-questions list are no longer accurate.
Also applies to: 49-53
| 4. Connect the integrations. Hand the user the connection link, wait for them to finish, then | ||
| re-check. You never connect on their behalf. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify the API-key connection path.
Lines 124-125 say the agent must never connect on the user's behalf, but Lines 221-222 later instruct it to create needs_input connections after collecting the secret. That contradiction will dead-end API-key integrations depending on which instruction the model follows. Narrow the prohibition to OAuth approval, or explicitly carve out the API-key flow.
Also applies to: 221-224
1 participant
Summary
Implements Part B of the agent-skills design. Adds three new platform build skills and registers them in the static workflow catalog so they can be referenced via
@ag.embedunder reserved__ag__slugs:build-your-first-app(__ag__build_your_first_app) — the orchestrator skill that maps the build flow and its stop points.discover-and-wire-tools(__ag__discover_and_wire_tools) — the tested draft promoted to a platform skill, with the section-3.3 edits (usesinstructions.agents_mdand the flattoolskey; self-modify viacommit_revisioninstead of thecreate-agenta-agentcurl skill).set-up-triggers(__ag__set_up_triggers) — cron + event-trigger skill.Single-sources
agenta-getting-started: the canonical body stays the SDK constantGETTING_STARTED_WITH_AGENTA_SKILL; the stale, never-loaded on-disk copy atservices/agent/skills/agenta-getting-started/SKILL.mdis dropped so the two cannot drift. No on-disk copies were added for the new skills, matching the design lean to drop on-disk skill copies.Slug rule:
__ag__+ name with hyphens turned to underscores. The force-skills mechanism was left untouched (out of scope). The build-kit overlay / default-agent-config wiring is frontend-owned and out of scope here.Implements the #4918 design. DRAFT for review tomorrow, do not merge.
Implementation (Codex, model gpt-5.5, xhigh)
Files changed
sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py— added the three new platform-skill slugs andSkillTemplateconstants.api/oss/src/core/workflows/static_catalog.py— registered the three new__ag__*static skill entries (same pattern asagenta-getting-started).Files dropped
services/agent/skills/agenta-getting-started/SKILL.mdviagit rm.services/agent/skillspath is still copied/mounted by current Docker/dev-compose files. (No code references the dropped file; flagged for review.)Ruff: pass (
ruff formatleft files unchanged;ruff check --fixclean).Tests: pass — API unit
1040 passed; SDK agents unit441 passed.The #4918 design doc is included under
docs/design/agent-workflows/projects/agent-skills/so reviewers can read the design alongside the implementation.