| name | agno-implementer |
| description | Execute an AgentOS implementation plan to completion — create/edit files, register agents, add evals, validate, smoke-test, update AGENTS.md, write a report. Use when a plan exists and you want it built. Covers Agno conventions and AGENTS.md update mapping. |
| argument-hint | ["path to the plan doc in project-docs/plans/","or describe what to implement"] |
Agno Implementer
Execute an AgentOS implementation plan doc to completion. Creates and
edits the files the plan specifies, registers the agent/team/workflow,
adds eval cases, validates, smoke-tests, then performs two finalization
steps: a surgical update to AGENTS.md and a written implementation
report.
When to use this skill
- A plan doc exists at
project-docs/plans/<slug>-plan.md
- You want to build what the plan specifies
- You need to know which AGENTS.md section to update and how
- You need to write the implementation report
Step 1 — Read and verify the plan
Read the plan doc. If it doesn't exist or is incomplete (missing sections,
no verified APIs), stop and tell the user to run the Agno Planner first.
For each Agno API the plan uses, verify it against the agno-docs MCP
server. If the plan's recorded signature conflicts with the MCP server,
trust the MCP server and flag the discrepancy.
Step 2 — Implement the plan
Follow the plan's "Files" section. Create each new file, edit each
existing file. Follow the plan's skeleton exactly — the Agent(...) /
Team(...) / Workflow(...) constructor, INSTRUCTIONS, tools, DB
factory, guardrails. Use the todo tool to track progress — one item
per file plus items for verify, register, evals, validate, format,
smoke-test, AGENTS.md update, report.
Step 3 — Validate and smoke-test
- Run
./scripts/format.sh to format new and edited files.
- Run
./scripts/validate.sh. Fix any errors in scope. Do not declare
done until it passes.
- Smoke-test:
docker compose restart agentos-api, then confirm the
new agent/workflow loads (check logs or hit the agents endpoint).
Per AGENTS.md, a restart is required for newly-registered modules.
Step 4 — Update AGENTS.md
This is a required finalization step, not optional. The plan's section 13
specifies what to update. Follow the
AGENTS.md update guide for the
section-to-content mapping and surgical edit conventions.
Key rules:
- Read the current
AGENTS.md before editing. Match the existing format
of the section you're updating (table rows, bullet lists, prose).
- Add the minimum entry that makes the new capability discoverable — a
Key Files row, a Domain Modules entry, an Environment Variables row,
or a Guardrails row. Don't rewrite sections.
- If the capability introduces a new env var, add it to the Environment
Variables table.
- If the capability introduces a new guardrail, add it to the Guardrails
table.
- Run
./scripts/format.sh after editing AGENTS.md (it's Markdown, but
the repo formatter keeps prose consistent).
Step 5 — Write the implementation report
Write the report to project-docs/reports/<slug>-report.md using the
report template. The report is the
handoff artifact for the next agent or human who needs to implement a
similar plan.
The report MUST cover:
- What was implemented — files created/edited, one line each.
- Issues encountered — plan-vs-repo drift, API mismatches, validation
failures, smoke-test problems, and how each was resolved.
- Guide for next agents — patterns that worked, gotchas hit, things
to check before starting a similar plan, links to the plan doc and
any reference files that were useful.
Step 6 — Report to the user
Summarize: files created/edited, validation result, smoke-test result,
AGENTS.md sections updated, report path, and any plan discrepancies
flagged. Do not deploy.
Gotchas
- AGENTS.md is the source of truth. If the implementation changes
what's configured (new agent, new env var, new guardrail), AGENTS.md
MUST reflect it. The environment manifest (
app/environment.py) is the
machine truth; AGENTS.md is the human narrative. Both must stay in sync.
- Don't rewrite AGENTS.md sections. Add entries to existing tables
and lists. Preserve the existing format and ordering.
- The report is not optional. It's how knowledge compounds across
implementations. Skip it and the next agent starts from scratch.
docker compose restart agentos-api is required for newly-registered
agents — uvicorn hot-reload is unreliable for new modules.
References
