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 skippedNo new commits to review since the last review. ⚙️ 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:
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
🤖 The AI agent says: What to review on this PR:
|
|
🤖 The AI agent says: Superseded by #4930 — same content, rebuilt as a clean GitButler stack. Closing this one. |
1 participant
Context
When a user creates a new agent and starts a build conversation, the agent has no guidance on the build flow: which tools to call, in what order, where to stop for the user, and what the footguns are. Without skills, the model guesses the sequence. This PR adds the three missing platform skills that teach the build flow.
Design:
docs/design/agent-workflows/projects/agent-skills/design.mdChanges
Three new platform skills, each registered under a reserved
__ag__slug in the static catalog. They reach a running agent via the build-kit overlay (owned by thedefault-agent-configproject, PR #4926) as@ag.embedentries.build-your-first-app__ag__build_your_first_appdiscover-and-wire-tools__ag__discover_and_wire_toolsset-up-triggers__ag__set_up_triggersFiles changed:
sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py— three newSkillTemplateconstants and their slug constants.api/oss/src/core/workflows/static_catalog.py— three new entries in_STATIC_WORKFLOWS, following the existing_skill_revisionpattern.File dropped:
services/agent/skills/agenta-getting-started/SKILL.md— removed. The canonical content is theGETTING_STARTED_WITH_AGENTA_SKILLSDK constant; the runner serves that constant to the sandbox, not the on-disk file. The file had drifted from the constant and would mislead anyone who read it. Single-sourcing removes the drift. The parentservices/agent/skills/directory is still mounted by dev-compose; the deletion only removes this one stale file.No new on-disk skill files were added for the new skills (matching the design decision to keep content in SDK constants, not the filesystem).
Scope / risk
The new skills name tools that do not exist yet (
find_triggers,create_schedule,create_subscription, etc.). Those are added by PR #4928. Until #4928 merges, the skills refer to tools the agent cannot call. The skill content is placeholder prose and will be revised when the build flow is finalized.The
services/agent/skills/path is still referenced in some design and QA docs as a place where skills live. Those references are now stale foragenta-getting-started. No Docker or compose file reads theSKILL.mdfile contents; the runner composes skills from the wire payload, not from disk.Tests
1040 passed(Codex-reported; includesstatic_catalogcoverage via existing tests).441 passed(Codex-reported).ruff formatleft files unchanged;ruff check --fixclean.No new dedicated test file was added for
agenta_builtins.py. The existing SDK test suite covers theSkillTemplatemodel shape; the slug constants are trivial string values.How to QA
Prerequisites: local dev stack.
Steps:
GET /api/workflows/revisions/?slug=__ag__build_your_first_app(with a valid project API key).__ag__discover_and_wire_toolsand__ag__set_up_triggers.services/agent/skills/agenta-getting-started/SKILL.mdno longer exists in the repo.Expected result: Each slug returns a revision with
data.parameters.skill.contentset to the matching skill body. The deleted file is gone.Automated tests:
Edge cases: Confirm that removing the on-disk
SKILL.mddoes not break any running-container path. The runner atservices/agent/src/engines/skills.tswrites skill files into the sandbox from the wire payload, not fromservices/agent/skills/. A quick grep for the path confirms no code reference.https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc