Deploy & Test

Once you have written a skill, you need to deploy it, install it into a workspace, and verify it works. This page covers all three steps.

Deploy

CLI

Deploy via CLI

From your skill’s root directory (where aerostack.json lives):

1. Authenticate

   aerostack auth login

2. Select your project

   aerostack project use my-project

3. Deploy

   aerostack deploy skill

   The CLI reads your aerostack.json, bundles the Worker code, and deploys it to your project. You will see output like:

   Deploying skill: send-email
     Bundling src/index.ts...
     Uploading to project my-project...
     Skill deployed successfully.
   
     Skill ID:   sk_abc123def456
     Name:        send-email
     Tool:        send_email
     Status:      active

Note

The CLI automatically detects the skill type from "type": "skill" in aerostack.json. You do not need to specify it manually.

Admin Dashboard

Deploy via Admin Dashboard

1. Go to app.aerostack.dev and sign in
2. Navigate to Skills in the sidebar
3. Click Create Skill
4. Paste your skill code into the editor
5. Fill in the tool definition (name, description, input schema)
6. Click Deploy

The dashboard provides a code editor with syntax highlighting and a JSON schema editor for the tool definition. You can also upload a zip of your skill directory.

---

Install into a Workspace

A deployed skill is not usable until it is installed into a workspace. Once installed, every consumer of that workspace can call it.

CLI

Install via CLI

# Set the active workspace
aerostack workspace use my-workspace

# Install the skill
aerostack skill install send-email

After install, the skill’s tool is available in the workspace as send-email__send_email (namespaced as {skill-slug}__{tool_name}).

To verify installation:

aerostack skill list

Output:

Workspace: my-workspace

  Skill              Tool                          Status
  send-email         send-email__send_email        active
  generate-pdf       generate-pdf__generate_pdf    active

Admin Dashboard

Install via Admin Dashboard

1. Go to your project in the Admin Dashboard
2. Navigate to Workspaces and select your workspace
3. Click Add Skills
4. Select the skill from the list (your deployed skills and Hub skills)
5. Click Install

The skill appears in the workspace’s tool list immediately.

---

Test Locally

Before deploying, you can test your skill locally using the Aerostack CLI’s development server.

1. Start the local dev server

   aerostack dev

   This starts a local server (default port 8787) with simulated bindings for Database, Cache, Storage, and other platform services.

2. Send a test request

   curl -X POST http://localhost:8787 \
     -H "Content-Type: application/json" \
     -d '{
       "to": "test@example.com",
       "subject": "Test Email",
       "body": "<h1>Hello</h1><p>This is a test.</p>"
     }'

3. Check the response

   {
     "success": true,
     "email_id": "abc123",
     "to": "test@example.com",
     "subject": "Test Email"
   }

Caution

Secrets (like RESEND_API_KEY) are not available in the local dev environment by default. Create a .dev.vars file in your skill’s root directory to provide them locally:

RESEND_API_KEY=re_test_xxxxxxxxxxxxx
DEFAULT_FROM_EMAIL=test@example.com

Never commit .dev.vars to version control. Add it to .gitignore.

Testing with environment bindings

If your skill uses Database, Cache, or Storage bindings, the CLI creates local instances automatically. To set up a local database schema:

# Apply your schema to the local database instance
aerostack db execute --local --file=schema.sql

Then aerostack dev will use the local database with your schema applied.

---

Verify in Workspace

After deploying and installing, verify the skill works end-to-end by calling it through the workspace.

Using an LLM client

Connect any MCP-compatible LLM client (Claude Desktop, Cursor, etc.) to your workspace URL. Ask the LLM to use your skill:

“Send an email to alice@example.com with the subject ‘Weekly Report’ and the body ‘Here is your weekly summary.’”

The LLM will discover the send_email tool in the workspace and call it.

Using the workspace API directly

You can also call skills through the workspace REST API:

curl -X POST https://your-project.aerostack.dev/api/v1/workspace/my-workspace/tools/send-email__send_email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alice@example.com",
    "subject": "Weekly Report",
    "body": "Here is your weekly summary."
  }'

Checking logs

View skill execution logs in the Admin Dashboard under Skills > select your skill > Logs. Logs show:

• Request timestamp
• Input parameters (redacted for secrets)
• Response status code
• Execution duration
• Any errors

---

Updating a Deployed Skill

To update a skill that is already deployed:

# Make your changes to src/index.ts or aerostack.json
# Then redeploy
aerostack deploy skill

The update is applied immediately. All workspaces that have the skill installed will use the new version. There is no need to reinstall.

Note

If you change the tool.input_schema in aerostack.json, LLM clients will pick up the new schema on their next tool discovery call. Existing conversations may need to refresh their tool list.

Removing a Skill

Remove from a workspace

aerostack skill remove

This launches an interactive prompt to select which skill to remove from the active workspace.

Delete the deployment

To delete the skill entirely (removes it from all workspaces):

1. Go to Skills in the Admin Dashboard
2. Select the skill
3. Click Delete

---

Troubleshooting

Problem	Cause	Fix
Skill deploys but is not callable	Not installed in any workspace	Run aerostack skill install <slug>
LLM does not discover the skill	Client has stale tool list	Reconnect the LLM client or refresh tools
”Method not allowed” error	Skill only handles POST, client sent GET	Ensure your skill handles the correct HTTP method
Secret not available	.dev.vars missing or secret not set	Run aerostack secrets set KEY value for deployed, or add to .dev.vars for local
Local DB is empty	Schema not applied	Run aerostack db execute --local --file=schema.sql

Next Steps

• Publish to Hub — share your skill with the Aerostack community
• CLI skill commands — full reference for all skill-related CLI commands