author-agent

name	author-agent
description	Use when the user wants to create or edit an ArchAstro agent's config files before deployment, including AgentTemplate files, Script configs, custom tools, routines, and environment setup. Trigger phrases include "build this agent", "write the template", "create the scripts", "set up the routines", "author this agent config".
allowed-tools	["Bash(archagent:*)"]

ArchAstro Agent Authoring

Create or update the config files for a config-driven ArchAstro agent before deployment.

This skill assumes the ArchAgent CLI is already installed and authenticated. Use the /archagents:install and /archagents:auth commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill.

Always Start with State

Every invocation must begin by understanding the current project state:

archagent auth status

If the user is in a repo, inspect whether a configs/ directory already exists and whether the agent already has Script or AgentTemplate files.

Routing

Local config directory not initialized

If the user doesn't have a configs/ directory set up yet, route to the manage-configs skill first. That skill owns archagent init --enable-configs, local file layout, and the sync/deploy workflow.

User wants to author or modify agent configs

1. Start from CLI-backed templates, not memory:

   • For new config objects, use:

     archagent describe configsample <Kind>
     

   • For Script configs, always use:

     archagent describe scriptdocs
     archagent describe configsample Script
     

     The script docs are the live source of truth. Do not invent or paraphrase the language from memory.

2. Use the standard config-driven model:

   • Script logic lives in kind: Script configs.
   • Agent behavior lives in an AgentTemplate.
   • Custom tools should use kind: custom, handler_type: script, and config_ref pointing at Script configs.
   • MCP server tools should use the builtin mcp_server tool with builtin_tool_config.mcp_server_ref or builtin_tool_config.integration_id. Do not put kind: MCPServer directly in the agent's tools: list.
   • When creating configs outside a project directory, use -f to read from a file:

     archagent create config -k AgentTemplate -f configs/agents/my-agent.yaml
     

3. Validate early:

   archagent validate config -k <Kind> -f <path>
   

   Run validation before deploy whenever the user changes Script or template files.

4. Deploy through the normal flow after authoring:

   • If the agent has Script configs or other supporting files, sync them first:

     archagent deploy configs
     

     This pushes local config files (Scripts, templates) but does not create agents. Skip this step if the agent only has a single AgentTemplate file — deploy agent handles its own config upload.
   • Then provision the agent from its template:

     archagent deploy agent <yaml-file>
     

     This uploads the template config and creates the agent with its routines, tools, and installations.
   • Important: deploy configs and deploy agent are different commands. Use deploy configs to sync a directory of config files; use deploy agent to create an agent from a template.

Authoring Rules

Script configs

• Load the build_script skill for detailed script authoring guidance, including syntax examples, common mistakes, and the validation/test/deploy workflow.
• Treat the script language as a functional expression language, not a general-purpose imperative language.
• Use archagent describe scriptdocs for exact syntax and available namespaces.
• If a script fails validation, prefer rewriting toward the sample/reference instead of trial-and-error improvisation.

Routine configs inside templates

• Scheduled routines need both:
  • schedule: "<cron>"
  • event_type: schedule.cron
• Do not put schedules under nested event_config.schedule.
• To discover valid event types and their payload schemas:

  archagent list events
  archagent describe event <event-name>
  

  The payload schema from describe event shows what $ contains in the routine's script handler.

Chain routines (linear multi-step routines)

When a single script or workflow isn't enough, use handler_type: chain — a linear sequence of preset / script / workflow_graph steps executed in order. Each step's output is addressable by name by downstream steps. Steps live under steps: in the template and each needs a unique name.

Chain-step script input shape: Scripts that run inside a chain step do NOT see the raw event at $. Their input is wrapped as {"trigger": <event payload>, "inputs": {"<step_name>": <upstream_output>, ...}}, so they must address the trigger via $.trigger.<field> and upstream outputs via $.inputs.<step_name>. Single-handler script routines (handler_type: script) continue to see the raw event payload at $. This only applies to chain steps — see the build-script skill for details.

Config references

• Prefer human-readable config_ref values that match deployed config lookup keys.
• Do not convert refs to raw cfg_... IDs unless explicitly debugging a broken environment.

MCP server tools

Use MCP when the agent needs a remote MCP-compatible tool server such as Atlassian, Linear, Stripe, or an internal MCP server. MCP tools are attached as the builtin mcp_server tool; system MCP servers are attached by existing integration ID, while custom MCP servers are referenced by config lookup key, virtual path, or config ID.

For OAuth-backed system servers, the matching integration credential must be connected before the tool config can reference it. For Atlassian, use provider mcp:system:mcp-atlassian and let the platform discover OAuth from https://mcp.atlassian.com. Do not configure Atlassian MCP with auth.atlassian.com credentials.

archagent list integrations --provider mcp:system:mcp-atlassian
archagent authorize integration <integration_id>

If no integration exists yet:

archagent create integration \
  --provider mcp:system:mcp-atlassian \
  --auth-type oauth \
  --org <org_id>

archagent authorize integration <integration_id>

Then copy the connected integration ID into the agent tool config:

tools:
  - tool_type: builtin
    builtin_tool_key: mcp_server
    builtin_tool_config:
      integration_id: <integration_id>
    status: active

For a custom MCP server, define a separate MCPServer config and then reference it from the agent. If the server uses a static bearer token, store it as an org environment variable with archagent create orgenvvar --org <org_id> --key INTERNAL_MCP_TOKEN --value "<token>", then reference it with secret_env!. Do not paste plaintext tokens into config YAML. Use secret_value! only for intentional embedded ciphertext; archagent create configsecret <token> calls the platform encryption API and prints the ciphertext for that field.

kind: MCPServer
key: internal-tools
name: Internal Tools
url: https://mcp.example.com/mcp
auth:
  type: bearer
  token:
    secret_env!: INTERNAL_MCP_TOKEN

tools:
  - tool_type: builtin
    builtin_tool_key: mcp_server
    builtin_tool_config:
      mcp_server_ref: internal-tools
    status: active

Environment variables

• For org users, prefer org-scoped environment variables when they are sufficient for the agent's needs.
• Do not default users into app-scoped env-var flows unless the use case truly requires app scope.

Recovery Rules

• If the user asks for a brand-new Script and the language shape is unclear, run archagent describe scriptdocs before drafting.
• If validation fails, surface the exact failing field or syntax problem. Do not immediately switch to lower-level provisioning commands.
• If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to deploy-agent.

Command Conventions

• All config commands are verb-first: archagent list configs, archagent create config, archagent deploy configs, archagent sync configs, archagent validate config, etc.
• There is no archagent configs namespace. Do not use archagent configs <verb> — always put the verb first.

Response Rules

• Do not inspect or edit credential files directly — use the CLI only.
• Do not ask the user to pick raw subcommands when intent is clear.
• Keep responses concise and operational.
• Prefer the golden path over fallback commands.