Author a Sikaru agent
An agent is one Markdown file: optional YAML frontmatter for settings, then the
instructions. The server is the only parser and compiler. Send the exact file. Don't
compute digests or rebuild the document from parsed fields.
Before writing anything, read https://sikaru.ai/agent-guide.md. It has worked
documents, mention rules and hosted invocation snippets. The frontmatter schema is
https://sikaru.ai/schemas/agent-document.json.
The document
---
tools:
web_search:
enabled: false
bash:
policy: require_approval
web:
allow_domains: [pandas.pydata.org]
setup:
packages:
pip: [pandas]
---
# Data helper
Answer questions about the CSV files in the workspace. Load them with pandas,
show the code you ran, and state any rows you dropped or values you assumed.
model: an ID from sikaru inference models. Leave it out to use the project
default.
tools: turn the built-in tools bash, workspace, agents, memory,
web_search and web_fetch on or off, and set a policy of allow,
require_approval or deny. All are on by default.
web: set allow_domains or block_domains.
setup: install pip and npm packages, run commands, clone repos.
access, budget, sources: see the agent guide.
- Apps and MCP servers: connect them to the project first, in the dashboard or with
sikaru agent connections. Then mention them in the instructions as @app/github
or @mcp/research. Integrations go through Composio apps or custom remote MCP
servers. Naming a tool in the instructions doesn't grant it. To narrow a grant:
access:
"@app/github":
tools: [GITHUB_CREATE_ISSUE]
policy: require_approval
The lifecycle
The project comes from -p or from sikaru config set project (see sikaru-setup).
# 1. Check, then create. Choose an unused slug; if it's taken, inspect that agent
# rather than overwrite it. `push` never creates an agent.
sikaru agent validate AGENT --file agent.md
sikaru agent create AGENT --file agent.md --name "Display name" # add --personal to keep each person's conversations private (fixed at creation)
# 2. Edit: pull the saved draft and its revision, change it, push with that revision.
sikaru agent pull AGENT --file agent.md --query revision
sikaru agent push AGENT --file agent.md --revision REVISION
# 3. Review the access delta, show it to the user, and publish only with their OK.
sikaru agent review AGENT --revision REVISION --format json > review.json
sikaru agent publish AGENT --revision REVISION --access-digest "$(jq -r .accessDigest review.json)"
# Add --live-version N after the first publication. Pass --acknowledge-widening or
# --acknowledge-removals only for the changes the user actually reviewed.
# 4. Run it. Leave out the task to start a conversation.
sikaru agent run AGENT "Which pandas function reads a CSV file?"
sikaru agent run AGENT -m MODEL_ID --prompt-file task.md
sikaru agent run AGENT --compute local -C "$PWD" "..." # tools run in this workspace with the user's OS permissions
sikaru agent logs RUN_ID --follow
sikaru agent stop RUN_ID
sikaru agent run exit codes:
| Code |
Outcome |
What to do |
| 0 |
completed |
Report the result. |
| 1 |
failed |
Read sikaru agent logs RUN_ID, then fix the document or the input. |
| 2 |
approval required |
Show the pending action to the user, and pass on their decision. |
| 3 |
cancelled |
Report it. |
| 4 |
recovery required |
Follow the next command in the result. |
| 5 |
paused for funding |
See credits in sikaru-setup, then resume with next. |
A CLI timeout doesn't cancel a hosted run. Use sikaru agent stop.
Rules
- A saved draft doesn't change live behavior. Only
publish does, and eval run
tests the live version.
- On a stale-revision conflict, pull the newer draft and reconcile it with the user.
Don't retry over someone else's work.
- Never change mentions or
access as part of an automatic prose rewrite.
- Never put credentials in a document. Shared secrets need 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.
- Personal apps and secrets resolve to the signed-in runner. A project key doesn't
become a user because you pass a
user_id label.
- Verify the returned session and its outcome. Creation alone isn't success.
For hosted invocation from an application (curl, Python or TypeScript), see the
"Hosted invocation snippets" section of the agent guide and
https://docs.sikaru.ai/run/runs-and-tool-requests.md.
1---2name: author-sikaru-agent3description: Write, validate, publish and run a Sikaru managed agent from one Markdown agent document with the Sikaru CLI. Use when the user wants to build, deploy, host, edit, review, publish, test or run a Sikaru agent, give an agent tools, apps or MCP servers, or turn instructions into a hosted agent.4metadata:5 source: https://skillmd.com/skills/aadi-labs/author-sikaru-agent6---78# Author a Sikaru agent910An agent is one Markdown file: optional YAML frontmatter for settings, then the11instructions. The server is the only parser and compiler. Send the exact file. Don't12compute digests or rebuild the document from parsed fields.1314Before writing anything, read https://sikaru.ai/agent-guide.md. It has worked15documents, mention rules and hosted invocation snippets. The frontmatter schema is16https://sikaru.ai/schemas/agent-document.json.1718## The document1920```markdown21---22tools:23 web_search:24 enabled: false25 bash:26 policy: require_approval27web:28 allow_domains: [pandas.pydata.org]29setup:30 packages:31 pip: [pandas]32---33# Data helper3435Answer questions about the CSV files in the workspace. Load them with pandas,36show the code you ran, and state any rows you dropped or values you assumed.37```3839- `model`: an ID from `sikaru inference models`. Leave it out to use the project40 default.41- `tools`: turn the built-in tools `bash`, `workspace`, `agents`, `memory`,42 `web_search` and `web_fetch` on or off, and set a `policy` of `allow`,43 `require_approval` or `deny`. All are on by default.44- `web`: set `allow_domains` or `block_domains`.45- `setup`: install `pip` and `npm` packages, run `commands`, clone `repos`.46- `access`, `budget`, `sources`: see the agent guide.47- Apps and MCP servers: connect them to the project first, in the dashboard or with48 `sikaru agent connections`. Then mention them in the instructions as `@app/github`49 or `@mcp/research`. Integrations go through Composio apps or custom remote MCP50 servers. Naming a tool in the instructions doesn't grant it. To narrow a grant:5152```yaml53access:54 "@app/github":55 tools: [GITHUB_CREATE_ISSUE]56 policy: require_approval57```5859## The lifecycle6061The project comes from `-p` or from `sikaru config set project` (see `sikaru-setup`).6263```sh64# 1. Check, then create. Choose an unused slug; if it's taken, inspect that agent65# rather than overwrite it. `push` never creates an agent.66sikaru agent validate AGENT --file agent.md67sikaru agent create AGENT --file agent.md --name "Display name" # add --personal to keep each person's conversations private (fixed at creation)6869# 2. Edit: pull the saved draft and its revision, change it, push with that revision.70sikaru agent pull AGENT --file agent.md --query revision71sikaru agent push AGENT --file agent.md --revision REVISION7273# 3. Review the access delta, show it to the user, and publish only with their OK.74sikaru agent review AGENT --revision REVISION --format json > review.json75sikaru agent publish AGENT --revision REVISION --access-digest "$(jq -r .accessDigest review.json)"76# Add --live-version N after the first publication. Pass --acknowledge-widening or77# --acknowledge-removals only for the changes the user actually reviewed.7879# 4. Run it. Leave out the task to start a conversation.80sikaru agent run AGENT "Which pandas function reads a CSV file?"81sikaru agent run AGENT -m MODEL_ID --prompt-file task.md82sikaru agent run AGENT --compute local -C "$PWD" "..." # tools run in this workspace with the user's OS permissions83sikaru agent logs RUN_ID --follow84sikaru agent stop RUN_ID85```8687`sikaru agent run` exit codes:8889| Code | Outcome | What to do |90| --- | --- | --- |91| 0 | completed | Report the result. |92| 1 | failed | Read `sikaru agent logs RUN_ID`, then fix the document or the input. |93| 2 | approval required | Show the pending action to the user, and pass on their decision. |94| 3 | cancelled | Report it. |95| 4 | recovery required | Follow the `next` command in the result. |96| 5 | paused for funding | See credits in `sikaru-setup`, then resume with `next`. |9798A CLI timeout doesn't cancel a hosted run. Use `sikaru agent stop`.99100## Rules101102- A saved draft doesn't change live behavior. Only `publish` does, and `eval run`103 tests the live version.104- On a stale-revision conflict, pull the newer draft and reconcile it with the user.105 Don't retry over someone else's work.106- Never change mentions or `access` as part of an automatic prose rewrite.107- Never put credentials in a document. Shared secrets need the managed sandbox108 secrets capability and exact allowed HTTPS hosts. Read placeholders from109 `json.loads(os.environ["SIKARU_SECRET_PLACEHOLDERS"])["slug"]` and use them only110 in request headers.111- Personal apps and secrets resolve to the signed-in runner. A project key doesn't112 become a user because you pass a `user_id` label.113- Verify the returned session and its outcome. Creation alone isn't success.114115For hosted invocation from an application (curl, Python or TypeScript), see the116"Hosted invocation snippets" section of the agent guide and117https://docs.sikaru.ai/run/runs-and-tool-requests.md.