# Deploy & Test

> Deploy skills via CLI or Admin Dashboard, test locally, and verify they work in a workspace.

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

### Deploy via CLI

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

1. **Authenticate**

   ```bash
   aerostack auth login
   ```

1. **Select your project**

   ```bash
   aerostack project use my-project
   ```

1. **Deploy**

   ```bash
   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
   ```

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

### Deploy via Admin Dashboard

1. Go to [app.aerostack.dev](https://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.

```mermaid
flowchart LR
    D["Deploy Skill"]
    I["Install into Workspace"]
    U["Available to All Consumers"]

    D --> I --> U

    style D fill:#3b82f6,stroke:#2563eb,color:#fff
    style I fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style U fill:#10b981,stroke:#059669,color:#fff
```

### Install via CLI

```bash
# 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:

```bash
aerostack skill list
```

Output:

```
Workspace: my-workspace

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

### 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**

   ```bash
   aerostack dev
   ```

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

1. **Send a test request**

   ```bash
   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>"
     }'
   ```

1. **Check the response**

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

  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:

```bash
# 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:

```bash
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:

```bash
# 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.

  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

```bash
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**](/skills/publish-to-hub) — share your skill with the Aerostack community
- [**CLI skill commands**](/cli/skill-commands) — full reference for all skill-related CLI commands