For the complete documentation index, see llms.txt. This page is also available as Markdown.

Build and upload your app

In this guide, brief your agent, approve its design, review the generated files, and approve the upload.

This page uses many terms that are specific to custom app development. For definitions, refer to App components.

Step 1. Brief the agent

A clear brief gives the agent the facts it needs to build your custom app.

Before you start, have these items ready:

  • The URL of the third-party service’s official API documentation, or the path to its OpenAPI file saved in your project folder.

  • Two or three operations for the first version, for example, search contacts and create a contact. Each operation becomes a module in Make.

  • The name of the app (if you want to extend an existing app). The agent can list the existing apps in your Make zone.

To brief the agent:

1

Send the agent a prompt

Send the agent the following prompt:

Use the make-custom-apps skill to build a Make custom app.

Third-party service: <THIRD-PARTY SERVICE NAME>
API documentation: <URL OR PATH TO THE OPENAPI FILE>
First operations: <OPERATIONS>
Target: <A NEW PRIVATE APP, OR THE NAME OF THE EXISTING APP>

Read SKILL.md and the references that apply. Use the Make developer
documentation for the specifications of app components. Use the
third-party service's API documentation for endpoints, authentication,
and limits.

Before you write any files, propose the app's connections, modules,
and any RPCs, webhooks, or app functions it needs. For each module,
show the API operation it calls. If a fact is missing, ask me.
Don't invent endpoints or credentials.

After I approve the design, write the app definition files in this
project and validate them. Then show me the validation report.

When I approve the upload, load MAKE_API_KEY and MAKE_ZONE from
.env.local, upload the app as private with @makehq/sdk, and read the
definitions back from Make to verify them. Don't print the values of
MAKE_API_KEY or MAKE_ZONE.

Don't publish the app. Ask me before you run any action that creates
or changes data in the third-party service.

Replace the placeholders with actual values:

  • <THIRD-PARTY SERVICE NAME>: The service you’re building for, for example, Acme CRM.

  • <URL OR PATH TO THE OPENAPI FILE>: The URL or file path of the API documentation.

  • <OPERATIONS>: The operations you want the app to support, for example, list contacts and create a contact.

  • <A NEW PRIVATE APP, OR THE NAME OF THE EXISTING APP>: Enter a new private app to create one, or the name of the existing app.

2

Answer the agent's questions

If you don’t know an answer, tell the agent. The agent must not guess required values.

You've now briefed the agent. Next, the agent proposes a design.

Step 2. Approve the design

The design is the agent's proposal in the chat, before it writes any files. Check it against the third-party service's API documentation to avoid rewriting and uploading files later due to incorrect endpoints.

To approve the design:

1

Check the operation details

Check that the proposal lists the following details for each operation: the API method and path, authentication, inputs and outputs, and the Make module that runs the operation. If the proposal isn't a table, ask the agent for a table with one row per operation.

2

Compare methods and paths

Compare each method and path with the third-party service's API documentation.

3

Check for dedicated modules

Check that no operation relies only on the universal Make an API Call module. If one does, ask the agent to add a dedicated module for it.

4

Check live-data inputs

Check that each input field that needs live data has an RPC. For example, a dropdown that lists the third-party service's projects needs an RPC to load them. If an RPC is missing, ask the agent to add it.

5

Check instant triggers

Check that each instant trigger has a webhook, with a way to register and remove it. If either is missing, ask the agent to add it.

6

Approve or request changes

Reply in the chat that you approve the design, and tell the agent to write and validate the app definition files. Or tell the agent what to change.

You've now approved the design. Next, review the generated app definition files.

Step 3. Review the app definition files

The agent writes the app definition files in your project folder and validates them on your computer. The validation report shows whether the files are consistent.

To review the app definition files:

1

Review the file layout

Ask the agent to explain the file layout. The explanation shows which file defines which component.

2

Read the validation report

The report must cover the following checks:

  • The files are valid, and every component they refer to exists.

  • Each request matches the third-party service's API documentation.

  • The connection check sends a real request that confirms the credentials work.

  • Logs hide credentials.

  • Input fields, output fields, and sample data match.

  • Searches handle multiple pages and respect the requested limit.

  • App functions have tests, and the values 0 and false stay intact instead of counting as empty.

3

Resolve validation failures

If a check fails or is missing from the report, ask the agent to fix it and run the validation again.

4

Commit the files

Commit the files to version control, including any script the agent used to generate them. Version control tracks your changes, so you can compare or undo them. Don't commit .env.local.

You've now reviewed the files. Next, approve the upload.

The validation report shows that the files are consistent and that the requests match the third-party service’s API documentation. After the upload, you test that the app connects to the third-party service and that its modules run in Make. You learn how to do that in Connect and test your app.

Step 4. Approve the upload to Make

To upload your app to Make, the agent runs a script that uses the Make TypeScript SDK (@makehq/sdk) to create the app in your Make account and save each component.

Uploaded changes immediately save to the app in Make. If you extend an existing app, scenarios that use it run with the changed definitions.

To approve the upload:

1

Install the specified SDK

Ask the agent to install the SDK version that the skill specifies.

2

Review the upload proposal

The proposal must show the target (your Make zone, and the app's name and version, or that the app is new), the components it uploads, and the expected effect.

3

Approve the upload

Reply in the chat that you approve the upload.

4

Read the upload report

The report must show the Make zone, the app’s name and version, which components the agent uploaded and read back from Make, and anything missing or failed.

After you approve, the agent creates the app, adds its components, and reads the definitions back from Make to confirm that Make saved what you reviewed. The app remains private and unpublished. Authorized users can use it after installation in your organization.

You’ve now uploaded a private app to Make. The upload saves the app definition only. It doesn’t create a connection to the third-party service, prove that modules run, or publish the app.

If the agent reports an error, a timeout, or a partial upload, ask it to check what Make saved before it tries again. This check prevents duplicate apps.

Skill reference files

This section addresses AI agents directly. If your agent’s output is incorrect or incomplete, ask it to read this section and load the reference file that matches the task.

Load only the reference files you need for your current task. Each file covers one topic in the make-custom-apps skill. To read the files, see the references folder.

What you're working on
Reference file

Researching an API or inspecting an existing app

research-and-inventory.md

Base settings, authentication, connection validation, and secrets

base-and-connections.md

Requests, response mapping, files, errors, and throttling

requests-and-responses.md

Actions, searches, pagination, and limits

modules-and-pagination.md

Input fields, dynamic selectors, dependent fields, and RPCs

parameters-and-rpcs.md

Polling triggers and webhooks

webhooks-and-polling.md

Reusable app functions and their tests

iml-functions.md

SDK access, upload, readback, visibility, and release

tooling-and-release.md

Local review and test coverage

review-and-qa.md

API changes, compatibility, and version updates

maintenance.md

Sources that conflict or are out of date

source-hierarchy.md

Last updated