feat(agent): build skills (#4918) by mmabrouk · Pull Request #4930 · Agenta-AI/agenta

mmabrouk · 2026-06-29T10:54:42Z

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.md

Changes

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 the default-agent-config project, PR #4929) as @ag.embed entries.

Skill	Slug	Role
`build-your-first-app`	`__ag__build_your_first_app`	Orchestrator: names the steps, the order, and the stop points for the full build.
`discover-and-wire-tools`	`__ag__discover_and_wire_tools`	Find action tools and get their integrations connected. Promoted from a tested draft.
`set-up-triggers`	`__ag__set_up_triggers`	Set up a cron job or an event trigger and test it.

Files changed:

sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py — three new SkillTemplate constants and their slug constants.
api/oss/src/core/workflows/static_catalog.py — three new entries in _STATIC_WORKFLOWS, following the existing _skill_revision pattern.

File dropped:

services/agent/skills/agenta-getting-started/SKILL.md — removed. The canonical content is the GETTING_STARTED_WITH_AGENTA_SKILL SDK 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 parent services/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 #4931. Until #4931 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 for agenta-getting-started. No Docker or compose file reads the SKILL.md file contents; the runner composes skills from the wire payload, not from disk.

Tests

API unit: 1040 passed (Codex-reported; includes static_catalog coverage via existing tests).
SDK agents unit: 441 passed (Codex-reported).
ruff format left files unchanged; ruff check --fix clean.

No new dedicated test file was added for agenta_builtins.py. The existing SDK test suite covers the SkillTemplate model shape; the slug constants are trivial string values.

How to QA

Prerequisites: local dev stack.

Steps:

Call GET /api/workflows/revisions/?slug=__ag__build_your_first_app (with a valid project API key).
Repeat for __ag__discover_and_wire_tools and __ag__set_up_triggers.
Confirm services/agent/skills/agenta-getting-started/SKILL.md no longer exists in the repo.

Expected result: Each slug returns a revision with data.parameters.skill.content set to the matching skill body. The deleted file is gone.

Automated tests:

cd api && uv run python -m pytest oss/tests/pytest/ -k "static_catalog or skill" -v
cd sdks/python && uv run python -m pytest oss/tests/pytest/unit/agents/ -v

Edge cases: Confirm that removing the on-disk SKILL.md does not break any running-container path. The runner at services/agent/src/engines/skills.ts writes skill files into the sandbox from the wire payload, not from services/agent/skills/. A quick grep for the path confirms no code reference.

https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

vercel · 2026-06-29T10:54:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 29, 2026 8:50pm

coderabbitai · 2026-06-29T10:54:50Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 12370dec-9544-4e40-9195-a431f0d349db

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

📝 Walkthrough

Walkthrough

Three new builtin platform skills (build-your-first-app, discover-and-wire-tools, set-up-triggers) are defined as SkillTemplate constants with reserved slugs in the SDK, registered as immutable v1 entries in the static workflow catalogue, and the old SKILL.md placeholder content is removed.

Changes

Platform Getting-Started Skills

Layer / File(s)	Summary
Slug constants and SkillTemplate definitions `sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py`	Adds three reserved slug constants (`BUILD_YOUR_FIRST_APP_SLUG`, `DISCOVER_AND_WIRE_TOOLS_SLUG`, `SET_UP_TRIGGERS_SLUG`) and their corresponding `SkillTemplate` constants with full canonical body text. `AGENTA_FORCED_SKILLS` is unchanged.
Static catalogue registration + SKILL.md cleanup `api/oss/src/core/workflows/static_catalog.py`, `services/agent/skills/agenta-getting-started/SKILL.md`	New skill constants are imported and three entries are appended to `_STATIC_WORKFLOWS`, each pinned to a single `v1` revision. Old placeholder `SKILL.md` content is deleted.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Agenta-AI/agenta#4851: Touches the same agenta-getting-started skill area and edits agenta_builtins.py within the same getting-started module.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding agent build skills.
Description check	✅ Passed	The description is clearly related to the changeset and explains the added skills and removed file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/agent-skills-4918-v2

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

mmabrouk · 2026-06-29T10:56:47Z

🤖 The AI agent says: Review needed (draft, do not merge yet). Specifically:

Skill bodies — build-your-first-app and set-up-triggers use the placeholder bodies from the docs(agent): platform skills design for agent self-building #4918 design (sections 3.2 / 3.4). Confirm the prose is good enough to ship as a starting point, or flag wording to change. The tools they name (find_capabilities, create_schedule, find_triggers, etc.) don't all exist yet — that's owned by agent-builder-capabilities.
discover-and-wire-tools section-3.3 edits — verify the config-key rename (instructions.agents_md, flat tools) and the self-modify re-point (commit_revision instead of the create-agenta-agent curl skill) are correct against the current agent-template shape.
Dropping the on-disk agenta-getting-started/SKILL.md — confirm the single-source decision (SDK constant is canonical). Codex flagged that the parent services/agent/skills path is still copied/mounted by Docker/dev-compose, and the exact dropped path is still referenced in some design/QA docs (no code references it). Decide whether those need follow-up.
Slugs — __ag__build_your_first_app, __ag__discover_and_wire_tools, __ag__set_up_triggers (rule: __ag__ + name with hyphens→underscores). Confirm these are the slugs the build-kit overlay should embed.

Open questions from the design (sections 7–8) intentionally left undecided here: whether to fold set-up-triggers into the orchestrator, and whether agenta-getting-started should become part of the AGENTS.md preamble instead of a skill.

mmabrouk · 2026-06-29T10:57:09Z

🤖 The AI agent says:

What to review on this PR:

Skill content correctness. The three new SkillTemplate bodies in agenta_builtins.py are placeholder prose. The key question is whether each skill names the right tools and stop points for the build flow it covers. Read each body against the build-flow table in the design doc (sections 2.1 and 2.2) and confirm the tools and gates match.
services/agent/skills/agenta-getting-started/SKILL.md deletion. The runner does not read this file at runtime. But confirm no Docker or compose volume mount, CI test, or documentation fixture references this exact path (a quick grep -r 'agenta-getting-started/SKILL' services/ and docs/ is enough).
The services/agent/skills/ directory going forward. With this deletion, the directory holds no skill files. Should the directory and any Docker COPY/VOLUME entry that references it be cleaned up, or is it kept intentionally for future on-disk skills?
Missing test for the new slugs. The PR adds three slug constants (BUILD_YOUR_FIRST_APP_SLUG, etc.) to agenta_builtins.py but no test asserts they resolve through the static catalog. A one-liner test like the existing test_static_catalog_returns_getting_started would close this gap.

mmabrouk · 2026-06-29T10:58:50Z

🤖 The AI agent says: [inline at api/oss/src/core/workflows/static_catalog.py:112]

🤖 The AI agent says: 🎯 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.

mmabrouk · 2026-06-29T10:58:51Z

🤖 The AI agent says: [inline at docs/design/agent-workflows/projects/agent-skills/design.md:8]

🤖 The AI agent says: 📐 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.

mmabrouk · 2026-06-29T10:58:52Z

🤖 The AI agent says: [inline at docs/design/agent-workflows/projects/agent-skills/design.md:188]

🤖 The AI agent says: 📐 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.

mmabrouk · 2026-06-29T10:58:53Z

🤖 The AI agent says: [inline at docs/design/agent-workflows/projects/agent-skills/status.md:20]

🤖 The AI agent says: 📐 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.

mmabrouk · 2026-06-29T10:58:54Z

+3. Find the tools. Follow the `discover-and-wire-tools` skill. It calls `find_capabilities`
+   and reports which integrations need a connection.
+4. Connect the integrations. Hand the user the connection link, wait for them to finish, then
+   re-check. You never connect on their behalf.


🤖 The AI agent says: 🎯 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.

mmabrouk · 2026-06-29T10:59:56Z

@coderabbitai review

coderabbitai · 2026-06-29T11:00:02Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dc239317-e4be-4fa1-84e5-e262b0e8d0bb

📥 Commits

Reviewing files that changed from the base of the PR and between a2d4cd1 and 420f61c.

📒 Files selected for processing (3)

api/oss/src/core/workflows/static_catalog.py
sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py
services/agent/skills/agenta-getting-started/SKILL.md

💤 Files with no reviewable changes (1)

services/agent/skills/agenta-getting-started/SKILL.md

coderabbitai · 2026-06-29T11:03:49Z

+    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),
+        },
+    },


🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Gate these static entries until the trigger/tool surface exists.

These slugs become live as soon as they land in _STATIC_WORKFLOWS, but the paired skill content still directs the model into follow-up-only tool calls. In particular, build-your-first-app routes users to set-up-triggers, and that skill assumes find_triggers, create_schedule, create_subscription, test_subscription, and list_deliveries already exist. Shipping the catalog entries now turns those dead ends into runtime behavior for reserved __ag__* slugs. Keep them out of the static catalog until the tools land, or gate resolution behind availability.

mmabrouk · 2026-06-29T19:08:25Z

+    body=_BUILD_YOUR_FIRST_APP_BODY,
+)
+
+_DISCOVER_AND_WIRE_TOOLS_BODY = """\


I did not see this in the playground, is it wired in the other prs. check that everything is in sync at latest when merging

mmabrouk

lgtm. see comment

Add the build-your-first-app, discover-and-wire-tools and set-up-triggers skill constants (agenta_builtins) and register them in the static catalog; drop the on-disk getting-started SKILL.md now that skills are code-defined. Design docs live in the agent-design-docs branch. Claude-Session: https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

describeSkill now resolves the embed's sibling name or the referenced workflow's name (via staticEmbedName), falling back to the slug, so committed static/embedded skills render their human name instead of the raw __ag__* slug. Claude-Session: https://claude.ai/code/session_01LUTGjUDzSX1tiJwqnqACtj

mmabrouk added the needs-review Agent updated; awaiting Mahmoud's review label Jun 29, 2026

mmabrouk mentioned this pull request Jun 29, 2026

feat(agent): builder tools — triggers, cron, find_triggers (#4919) #4931

Draft

vercel Bot deployed to Preview June 29, 2026 10:56 View deployment

mmabrouk commented Jun 29, 2026

View reviewed changes

mmabrouk mentioned this pull request Jun 29, 2026

feat(agent): build skills (#4918) #4924

Closed

coderabbitai Bot reviewed Jun 29, 2026

View reviewed changes

mmabrouk force-pushed the feat/build-kit-4917-v2 branch from a2d4cd1 to 1a8f483 Compare June 29, 2026 12:07

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from 420f61c to a568150 Compare June 29, 2026 12:07

vercel Bot deployed to Preview June 29, 2026 12:08 View deployment

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from a568150 to 60620ae Compare June 29, 2026 13:13

vercel Bot deployed to Preview June 29, 2026 13:14 View deployment

mmabrouk force-pushed the feat/build-kit-4917-v2 branch from c1d6561 to 332c5d8 Compare June 29, 2026 16:54

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from 60620ae to 4b8d038 Compare June 29, 2026 16:54

vercel Bot deployed to Preview June 29, 2026 16:55 View deployment

mmabrouk commented Jun 29, 2026

View reviewed changes

mmabrouk added lgtm This PR has been approved by a maintainer and removed needs-review Agent updated; awaiting Mahmoud's review labels Jun 29, 2026

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from 4b8d038 to 851f2e0 Compare June 29, 2026 19:50

vercel Bot deployed to Preview June 29, 2026 19:51 View deployment

mmabrouk force-pushed the feat/build-kit-4917-v2 branch from d07809e to 65f298a Compare June 29, 2026 20:19

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from 851f2e0 to 2340380 Compare June 29, 2026 20:20

vercel Bot deployed to Preview June 29, 2026 20:21 View deployment

This was referenced Jun 29, 2026

docs(agent): platform skills design for agent self-building #4918

Closed

docs(agent): agent-builds-an-app design overview #4921

Closed

mmabrouk added 2 commits June 29, 2026 22:48

mmabrouk force-pushed the feat/build-kit-4917-v2 branch from 65f298a to b4873b7 Compare June 29, 2026 20:49

mmabrouk force-pushed the feat/agent-skills-4918-v2 branch from 2340380 to 505fb1b Compare June 29, 2026 20:49

vercel Bot deployed to Preview June 29, 2026 20:50 View deployment

Uh oh!

Conversation

mmabrouk commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Changes

Scope / risk

Tests

How to QA

Uh oh!

vercel Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

mmabrouk Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk commented Jun 29, 2026

Uh oh!

coderabbitai Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

mmabrouk left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mmabrouk commented Jun 29, 2026 •

edited

Loading

vercel Bot commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading