---
name: author-sikaru-agent
description: Author, validate, publish, and invoke a Sikaru managed agent from one Markdown document using the Sikaru CLI.
---

# Author a Sikaru agent

Read https://sikaru.ai/agent-guide.md before acting. It contains three worked
documents, exact CLI commands, mention rules, and hosted invocation snippets.
Frontmatter schema: https://sikaru.ai/schemas/agent-document.json.

1. Obtain the user's real project ID and server-side Sikaru API key. Keep the key
   in the environment, never in the document, generated source, or chat output.
2. Write `agent.md`. Preserve exact UTF-8 bytes; the server parses and compiles it.
3. For a new identity, use `sikaru managed-agents create_managed_agent` with
   `source.sourceKind` set to `agent_document` and `source.document` containing
   the exact file text. Use `jq --rawfile`, as shown in the guide, to preserve
   trailing newlines. Native `agents push` never creates an agent.
4. Pull the saved document and revision with `sikaru agents pull`. For edits,
   push with that revision. On a stale-save conflict, read the newer draft and
   reconcile with the author; do not blindly retry over another person's work.
5. Validate with `sikaru agents validate`. Resolve every blocking mention and
   project ceiling. Shared app and MCP connections must exist and be usable.
6. Test the saved document revision with an execution session using
   `environment: "draft"` and `draft_revision`. Review and explicitly acknowledge
   widened access. Draft tests never activate Live and isolate memory and files.
   The companion accepts `sikaru-authoring dev AGENT --project PROJECT --revision N`
   with the existing tenant/user labels; these do not establish a signed-in user.
7. Obtain `sikaru agents review` for the saved revision and inspect the access
   delta, then publish only with the user's authorization. Pass that review's
   `accessDigest` through `sikaru agents publish --access-digest`.
   Supply the current revision/live version and acknowledge the access changes
   actually reviewed. A saved draft does not change live behavior.
8. Fetch `sikaru agents snippets` for the real agent. Use its CLI, curl, Python,
   or TypeScript text to create a hosted session, append a turn, and stream events.
   Verify the returned session and outcome; do not claim success from creation alone.

Never change mentions or access settings as part of an automatic prose rewrite.
Never insert actual credentials into a document. Shared secrets require the managed
sandbox secrets capability and exact allowed HTTPS hosts. Read placeholders from
`json.loads(os.environ["SIKARU_SECRET_PLACEHOLDERS"])["slug"]` and use them only
in request headers. Local compute receives no placeholders. Respect per-request
approval decisions and never follow redirects with credential headers.
Personal app connections and secrets resolve the signed-in runner's own account.
Sign in through `sikaru auth login` to use them; a missing account pauses an
interactive turn to connect and resume. Personal sessions are readable in full
only by their runner. Agent schedules target `agent_slug`, use the Live version
at each occurrence, and start a fresh conversation by default. Personal scheduled
calls require the creator to have published Live and still belong to the project;
missing personal access fails that call and records a notice.
A project key does not become a signed-in user by supplying a `user_id` label.