agent-admin

Admin

This skill is for referencing and changing Agent settings (system_prompt, db_schema, Knowledge) from the CLI. A subset of the same operations as the Admin UI can be executed via the bundled Python scripts.

Prerequisites

• AWS credentials are configured in the terminal
• uv (Python tool manager) is installed

Each script uses PEP 723 inline metadata to boto3 is declared, souv run automatically resolves dependencies on first run.pyproject.toml or venv setup is not required.

Initial setup

When using this skill for the first time, ask the user the following:

1. Agent settings table name
   • Example: DwhAgentStack-DatabaseConfigTableXXXXXX-YYYYYY
   • Can be checked from CDK deploy output or the AWS console
2. AWS region
   • Example: ap-northeast-1

Once told, reuse it as-is in subsequent conversations. In the command examples below $TABLE / $REGION replace with the respective values.

Script list

All .kiro/skills/agent-admin/scripts/ It is located under. When Kiro executes it, call it with a workspace-relative path.

script	Purpose
list_agents.py	Get the Agent list
create_agent.py	Create a new Agent
get_agent.py	Get all attributes of one Agent (system_prompt, db_schema, Knowledge, metadata)
update_system_prompt.py	Replace system_prompt
upsert_knowledge.py	Add or replace one Knowledge entry
delete_knowledge.py	Delete one Knowledge entry by name

Each script returns JSON to stdout on success, and on failure outputs a message to stderr and exits non-zero. Only on success json.loads(stdout) please.

Terminology mapping

In the UI, scripts, and this document, all Knowledge It is called.

Rules for creating input files (important)

When passing text that may contain newlines or quotes, such as system_prompt or Knowledge entries, always Kiro の native fsWrite tool create a temporary file with, and pass that path to the --*-file argument.

• echo ... >, cat <<EOF >, shell-based file creation such as heredocs Do not use
• fsWrite does not go through the shell, so quoting, escaping, and EOF marker issues cannot occur in principle
• The script does not accept inline string arguments or stdin (file path passing only)

Operations

Get Agent list

uv run .kiro/skills/agent-admin/scripts/list_agents.py \
  --table-name "$TABLE" --region "$REGION"

Create a new Agent

If the user says they want to add a new Agent:

1. agent_name(display name) and system_prompt according to the user's request, and write the system_prompt to fsWrite to a temporary file
2. Execute the following

# system_prompt をファイルから読ませる場合
uv run .kiro/skills/agent-admin/scripts/create_agent.py \
  --table-name "$TABLE" --region "$REGION" \
  --agent-name "売上分析 Agent" \
  --system-prompt-file ./tmp/new_prompt.txt

# system_prompt を空で作る場合
uv run .kiro/skills/agent-admin/scripts/create_agent.py \
  --table-name "$TABLE" --region "$REGION" \
  --agent-name "売上分析 Agent"

db_schema is created empty. At Agent execution time, db_schema if is empty, the Agent Runtime automatically "default" Agent の db_schema is used as a fallback.

View the current state of the Agent

# default Agent
uv run .kiro/skills/agent-admin/scripts/get_agent.py \
  --table-name "$TABLE" --region "$REGION"

# 指定した Agent
uv run .kiro/skills/agent-admin/scripts/get_agent.py \
  --table-name "$TABLE" --region "$REGION" --id 3f2c1d4e-...

get_agent.py returns in a single call agent_name, system_prompt, db_schema, knowledge(array), created_at, updated_at all of them.--field There is no filtering like that (extract only the necessary parts on the Kiro side).

Beware of the db_schema fallback: When the target Agent's db_schema is empty,get_agent.py automatically returns id="default" の db_schema and adds db_schema_source: "default" to the output JSON (usually "self"). This is the same behavior as the Agent Runtime. Use db_schema to determine whether the db_schema_source you are currently viewing is your own or comes from the default.

Updating system_prompt

1. fsWrite to write the new system_prompt to a temporary file (e.g., ./tmp/new_prompt.txt）
2. Run the following

uv run .kiro/skills/agent-admin/scripts/update_system_prompt.py \
  --table-name "$TABLE" --region "$REGION" \
  --id 3f2c1d4e-... --prompt-file ./tmp/new_prompt.txt

--id is the Agent's ID. If omitted, default is targeted.

Adding / Replacing Knowledge

A Knowledge entry is a Markdown string in the following format:

---
name: <kebab-case の識別子>
description: <説明と、どの様な会話でこのknowledgeを使うかについて簡潔に>
---
<Markdown 形式の指示内容>

1. fsWrite to write one entry to a temporary file (e.g., ./tmp/k1.md）
2. Run the following

uv run .kiro/skills/agent-admin/scripts/upsert_knowledge.py \
  --table-name "$TABLE" --region "$REGION" \
  --id 3f2c1d4e-... --knowledge-file ./tmp/k1.md

--id is the Agent's ID. If omitted, default is targeted.

Behavior:

• From the file's leading frontmatter（--- (the YAML metadata block enclosed by name extract
• If the existing Knowledge has the same name if there is replace it in place, if not append to the end
• The result can be determined by the output JSON's action が "updated" か "added" or
• In the description, along with a concise explanation, briefly describe in what kind of conversation this Knowledge should be used.

Constraints:

• name must be a non-empty string (whitespace-only is not allowed)
• Write only one entry per file (files with multiple entries joined by --- are not supported)
• If you want to add multiple entries, write a file per entry and call upsert_knowledge.py in order

Deleting Knowledge

uv run .kiro/skills/agent-admin/scripts/delete_knowledge.py \
  --table-name "$TABLE" --region "$REGION" \
  --id 3f2c1d4e-... --name k1

--id is the Agent's ID. If omitted, default is targeted. --name must exactly match the name of the frontmatter of the deletion target. If it does not exist, the process exits with an error.

Updating db_schema

⛔ Modifying db_schema is strictly prohibited. This skill does not provide any means to change it.

db_schema is managed only through the Admin UI's CSV upload → AI analysis → Apply flow. Changing db_schema via CLI or scripts causes inconsistencies with the actual table definitions on Redshift and causes the Agent to generate incorrect SQL.

If a user requests a db_schema change:

• Explain that db_schema changes can only be made from the Admin UI
• Guide them to re-upload the CSV and Apply
• This skill only allows referencing db_schema (viaget_agent.py )

Notes

• Never change db_schema (strictly prohibited). Read-only access is allowed.
• Configuration changes are immediately reflected in Agent behavior (starting from the next /chat request)
• Before making changes, get_agent.py it is recommended to check the current value with
• Long text that requires input (system_prompt, Knowledge body) must always be fsWrite written to a temporary file with --*-file and then passed with

Error handling

• On success: exit 0, JSON to stdout
• On failure: non-zero exit, cause message to stderr, stdout empty

On failure, it returns in a form where the cause can be understood by reading the contents of stderr as is.get_agent.py In a situation where fallback is required with default If the Agent did not exist, it returns with exit 0 while outputting a warning to stderr (db_schema_source: "default", db_schema: ""）。Kiro は stdout の db_schema_source can be used to determine this.