# Scaffold Stack

> Generate a stackql-deploy stack with a stackql_manifest.yml and .iql resource files for provisioning cloud infrastructure. Accepts a description of the desired infrastructure or a specific provider and resources to provision.

- Skill: `stackql/scaffold-stack` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stackql/scaffold-stack`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stackql/scaffold-stack/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: stackql (https://skillmd.com/u/stackql)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stackql/scaffold-stack

---


You are helping the user create a new stackql-deploy stack for provisioning cloud infrastructure.

Input: `$@`

Follow these steps in order.

## Step 1 - Understand the requirements

Parse the user's input to determine:
- Which cloud provider(s) are involved (google, aws, azure, etc.)
- What resources need to be provisioned
- Any specific configuration requirements mentioned

If the input is vague, ask clarifying questions:
- Which cloud provider?
- What region/zone?
- What specific resources? (e.g., VPC, subnets, compute instances, storage buckets)
- Any naming conventions or project/subscription context?

## Step 2 - Check StackQL is installed and providers are available

```bash
command -v stackql
```

If not found, delegate to `/stackql-skills:install-stackql`.

Check if the required provider is pulled:

```bash
stackql exec "SHOW PROVIDERS;" --output json
```

If not, delegate to `/stackql-skills:pull-provider <provider>`.

## Step 3 - Discover resource schemas

For each resource the user wants to provision, get the schema:

```bash
stackql exec "DESCRIBE <provider>.<service>.<resource>;" --output json
stackql exec "SHOW METHODS IN <provider>.<service>.<resource>;" --output json
```

Use this to understand:
- What fields are available for INSERT (createorupdate methods)
- What fields are required
- What identifiers are needed for SELECT (to verify deployment)

## Step 4 - Determine stack directory

Ask the user where to create the stack, or use a sensible default:

```
<stack-name>/
  stackql_manifest.yml
  resources/
    <resource1>.iql
    <resource2>.iql
    ...
```

## Step 5 - Generate the stackql_manifest.yml

Create the manifest file following the stackql-deploy format:

```yaml
version: 2
name: <stack-name>
description: <description>
providers:
  - <provider>
globals:
  - name: global_tags
    value:
      managed_by: stackql-deploy
      environment: "{{ environment }}"

resources:
  - name: <resource-name>
    description: <resource description>
    props:
      - name: <prop-name>
        value: <value or "{{ var }}">
    exports:
      - <exported-field>
```

Key manifest conventions:
- Use Jinja2 template syntax (`{{ var }}`) for parameterized values
- Group related resources logically
- Define exports for values that downstream resources need
- Use `globals` for shared configuration like tags and environment

## Step 6 - Generate .iql resource files

For each resource in the manifest, create the corresponding `.iql` files. Each resource typically needs:

**`resources/<resource-name>.iql`** - Contains the StackQL queries for build, test, and teardown:

```sql
/*+ build */
INSERT INTO <provider>.<service>.<resource> (
  <field1>,
  <field2>,
  ...
)
SELECT
  '{{ prop1 }}',
  '{{ prop2 }}',
  ...
;

/*+ test */
SELECT count(*) as count
FROM <provider>.<service>.<resource>
WHERE <identifier> = '{{ resource_name }}'
AND <required_param> = '{{ param }}';

/*+ teardown */
DELETE FROM <provider>.<service>.<resource>
WHERE <identifier> = '{{ resource_name }}'
AND <required_param> = '{{ param }}';
```

Use the schema from Step 3 to populate the correct field names and required parameters.

## Step 7 - Generate a variables file (optional)

If the stack uses template variables, create an example variables file:

**`vars/dev.jsonnet`** or **`vars/dev.json`**:

```json
{
  "environment": "dev",
  "project": "my-project",
  "region": "us-central1"
}
```

## Step 8 - Report

Summarize what was created:

- List all files generated
- Explain the stack structure
- Provide the commands to deploy:

> To deploy this stack:
> ```bash
> pip install stackql-deploy  # if not installed
> stackql-deploy build <stack-name> dev --env-file vars/dev.json
> ```
>
> To test the deployment:
> ```bash
> stackql-deploy test <stack-name> dev --env-file vars/dev.json
> ```
>
> To tear down:
> ```bash
> stackql-deploy teardown <stack-name> dev --env-file vars/dev.json
> ```

Suggest reviewing the generated files and customizing values before deploying.