Skip to content

Commit f179e24

Browse files
patrikbraborecjirispilkaTC-MO
authored
docs: Refactor of Build with AI section (#2044)
I refactored the page and added instructions on "how to start building actors with AI". Basically, the idea is to provide an environment for "vibe coders", where they just copy and paste the instructions to AI, and the AI will create an actor together with AGENTS.md. Key decisions and comments: - I ignored the apify create command and instead provided the LLM with the actor structure with key details for actor.json, etc. It works pretty well. - I tested it, and I successfully built the actor several times. It also created the correct AGENTS.md, and I was able to push the Actor to the Console and run it. - The next improvement regarding the AGENTS.md/instructions should be done with the help of some kind of evals to systematically improve the AGENTS.md/instructions rather than guessing what might work. - I added links to install MCP through a button. There is a problem with Auth (our MCP requires Auth even for docs). If we do not solve the issue, I will just add a link to mcp.apify.com for now and add the buttons later. --------- Co-authored-by: Jiří Spilka <[email protected]> Co-authored-by: Michał Olender <[email protected]>
1 parent 2b91319 commit f179e24

File tree

8 files changed

+649
-110
lines changed

8 files changed

+649
-110
lines changed

‎sources/platform/actors/development/quick_start/build_with_ai.md‎

Lines changed: 56 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,99 @@
11
---
22
title: Build with AI
33
sidebar_position: 3
4-
description: Learn how to set up your environment, choose the right tools, and establish workflows for effective vibe coding
4+
description: Use pre-built prompts, refer to Apify docs via llms.txt, and follow best practices for effective vibe coding.
55
slug: /actors/development/quick-start/build-with-ai
66
toc_max_heading_level: 4
77
---
88

9-
**Set up your environment, choose tools, and build workflows for effective AI development.**
9+
**Use pre-built prompts, reference Apify docs via llms.txt, and follow best practices to build Actors efficiently with AI coding assistants.**
1010

1111
---
1212

13-
import { RULES_AND_INSTRUCTIONS_PROMPT } from "@site/src/utils/ai-prompts";
13+
import { AGENTS_PROMPT } from "@site/src/utils/agents-prompt";
1414
import PromptButton from "@site/src/components/PromptButton";
15+
import InstallMCPButton from "@site/src/components/InstallMCPButton";
16+
import copyForAI from "./images/copy-for-ai.png";
1517

16-
This guide explains how to enhance your development workflow by leveraging `llms.txt` and `llms-full.txt` with an AI assistant. You will learn how to provide foundational context and further refine AI's behavior with specific rules and instruction files.
18+
You will learn several approaches to building Apify Actors with the help of AI coding assistants. This guide includes independent instructions, tools, and best practices that you can use individually or combine together. Each section focuses on a specific part of the process such as prompt usage, Actor templates, Apify MCP server tools, or documentation integration, so you can follow only the parts that fit your development style.
1719

18-
## `llms.txt` and `llms-full.txt`
20+
## AI coding assistant instructions
1921

20-
Search engines weren't built for Large Language Models (LLMs), but they needs context. That's why we've created [`llms.txt`](https://docs.apify.com/llms.txt) and [`llms-full.txt`](https://docs.apify.com/llms-full.txt) for our documentation. These files follow the [growing standard](https://llmstxt.org/) for LLMs consumption.
22+
Use the following prompt in your AI coding assistant such as [Cursor](https://www.cursor.com/), [Claude Code](https://www.claude.com/product/claude-code) or [GitHub Copilot](https://github.com/features/copilot):
2123

22-
<table>
23-
<thead>
24-
<tr>
25-
<th>File</th>
26-
<th>Purpose</th>
27-
</tr>
28-
</thead>
29-
<tbody>
30-
<tr>
31-
<td><code>llms.txt</code></td>
32-
<td>Contains index of the docs page in Markdown, with links to all subpages in Markdown.</td>
33-
</tr>
34-
<tr>
35-
<td>
36-
<code style={{ whiteSpace: 'nowrap' }}>llms-full.txt</code>
37-
</td>
38-
<td>Contains a full dump of documentation in Markdown.</td>
39-
</tr>
40-
</tbody>
41-
</table>
42-
43-
### Use llms.txt and llms-full.txt
44-
45-
LLMs don't automatically discover `llms.txt` files, you need to add the link manually. Some tools like [Cursor](https://www.cursor.com/) provide settings for this.
24+
<PromptButton prompt={AGENTS_PROMPT} title="Use pre-built prompt for your AI coding assistant" />
4625

47-
#### Cursor
26+
The prompt guides AI coding assistants such as Cursor, Claude Code or GitHub Copilot to help users create and deploy an Apify Actor step by step. It walks through setting up the Actor structure, configuring all required files, installing dependencies, running it locally, logging in, and pushing it to the Apify platform and following Apify’s best practices.
4827

49-
Go to: **Settings -> Cursor Settings -> Indexing & Docs -> Add Doc**.
28+
### Quick Start
5029

51-
Now, you can just provide the link to Apify `llms-full.txt`:
30+
1. Create directory: `mkdir my-new-actor`
31+
1. Open the directory in _Cursor_, _Claude Code_, _VS Code with GitHub Copilot_, etc.
32+
1. Copy the prompt above and paste it into your AI coding assistant (Agent or Chat)
33+
1. Run it, and develop your first actor with the help of AI
5234

53-
```markdown
54-
https://docs.apify.com/llms-full.txt
55-
```
56-
57-
![Add llms-full.txt to Cursor](./images/cursor.png)
58-
59-
#### Windsurf
60-
61-
Open Windsurf Cascade, and add context via `@web`:
35+
:::info Avoid copy-pasting
6236

63-
![Add llms-full.txt to Windsurf](./images/windsurf.png)
64-
65-
:::note Windsurf @docs
66-
67-
Windsurf provides the `@docs` command, but you cannot customize it. It means that you cannot add your own documentation.
37+
The AI will follow the guide step-by-step, and you'll avoid copy-pasting from tools like ChatGPT or Claude.
6838

6939
:::
7040

71-
#### GitHub Copilot
72-
73-
Open Copilot Chat mode, and add context via `#fetch`:
41+
## Use Actor templates with AGENTS.md
7442

75-
![Add llms.txt to Copilot](./images/github-copilot.png)
43+
All [Actor Templates](https://apify.com/templates) have AGENTS.md that will help you with AI coding. You can use the [Apify CLI](/cli/docs) to create Actors from Actor Templates.
7644

77-
:::note GitHub Copilot and documentation
78-
79-
Similar to Windsurf, GitHub Copilot does not provide an option for adding your own documentation.
80-
81-
:::
82-
83-
#### Ask AI
84-
85-
New to Apify? Ask questions and provide the `llms.txt` link. Popular AI models can search the web. With the right context, you get better answers:
86-
87-
![Ask about Apify](./images/claude.png)
45+
```bash
46+
apify create
47+
```
8848

89-
## View pages as markdown
49+
If you do not have Apify CLI installed, see the [installation guide](/cli/docs/installation).
9050

91-
Every page in Apify documentation is available in markdown format. Simply add `.md` to any documentation URL to access the raw markdown content.
51+
The command above will guide you through Apify Actor initialization, where you select an Actor Template that works for you. The result is an initialized Actor (with AGENTS.md) ready for development.
9252

93-
For example:
53+
## Use Apify MCP Server
9454

95-
- [https://docs.apify.com/platform](https://docs.apify.com/platform) → [https://docs.apify.com/platform.md](https://docs.apify.com/platform.md)
96-
- [https://docs.apify.com/api](https://docs.apify.com/api) → [https://docs.apify.com/api.md](https://docs.apify.com/api.md)
55+
The Apify MCP Server has tools to search and fetch documentation. If you set it up in your AI editor, it will help you improve the generated code by providing additional context to the AI.
9756

98-
This is useful when you want to:
57+
:::info Use Apify MCP server configuration
9958

100-
- Copy documentation content for AI prompts
101-
- Reference exact markdown syntax
102-
- Access content programmatically
59+
We have prepared the [Apify MCP server configuration](https://mcp.apify.com/), which you can configure for your needs.
10360

104-
## Add rules
61+
:::
10562

106-
To get the most from AI Code Editors, add rules or instructions.
63+
## Provide context to assistants
10764

108-
See how to set up rules for your AI Code Editors:
65+
Every page in the Apify documentation has a **Copy for LLM** button. You can use it to add additional context to your AI assistant, or even open the page in ChatGPT, Claude, or Perplexity and ask additional questions.
10966

110-
- [Cursor Rules](https://docs.cursor.com/en/context/rules)
111-
- [Windsurf Rules](https://docs.windsurf.com/windsurf/cascade/memories#rules)
112-
- [GitHub Copilot instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
67+
<img src={copyForAI} alt="Copy for LLM" width="250" />
11368

114-
### Apify rules and instructions
69+
## Use `llms.txt` and `llms-full.txt`
11570

116-
The best rules and instructions are specific for individual use cases, but we provide a prompt to help you get start with creating rules and instructions:
71+
Search engines weren't built for Large Language Models (LLMs), but LLMs need context. That's why we've created [`llms.txt`](https://docs.apify.com/llms.txt) and [`llms-full.txt`](https://docs.apify.com/llms-full.txt) for our documentation. These files can provide additional context if you link them.
11772

118-
<PromptButton prompt={RULES_AND_INSTRUCTIONS_PROMPT}/>
73+
<table>
74+
<thead>
75+
<tr>
76+
<th>File</th>
77+
<th>Purpose</th>
78+
</tr>
79+
</thead>
80+
<tbody>
81+
<tr>
82+
<td><code>llms.txt</code></td>
83+
<td>Contains index of the docs page in Markdown, with links to all subpages in Markdown.</td>
84+
</tr>
85+
<tr>
86+
<td>
87+
<code style={{ whiteSpace: 'nowrap' }}>llms-full.txt</code>
88+
</td>
89+
<td>Contains a full dump of documentation in Markdown.</td>
90+
</tr>
91+
</tbody>
92+
</table>
11993

120-
:::info Keep your rules and instructions up to date
94+
:::note Provide link to AI assistants
12195

122-
As the project evolves, you might introduce new things. Always make sure that your rules and instructions are up to date.
96+
LLMs don't automatically discover `llms.txt` files, you need to add the link manually to improve the quality of answers.
12397

12498
:::
12599

‎sources/platform/actors/development/quick_start/images/copy-for-ai.png‎

72.6 KB
Loading

‎src/components/InstallMCPButton.jsx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import React from 'react';
2+
3+
import { ExternalLinkIcon } from '@apify/ui-icons';
4+
import { Text } from '@apify/ui-library';
5+
6+
import styles from './InstallMCPButton.module.css';
7+
8+
export default function InstallMCPButton({ link, label = 'Install MCP', children }) {
9+
if (!link) return null;
10+
11+
return (
12+
<a href={link} className={styles.button} target="_blank" rel="noopener noreferrer">
13+
<div className={styles.wrapper}>
14+
<div className={styles.iconWrapper} aria-hidden>
15+
<ExternalLinkIcon size={16} className={styles.icon} />
16+
</div>
17+
<Text
18+
size="regular"
19+
className={styles.label}
20+
>
21+
{children || label}
22+
</Text>
23+
</div>
24+
</a>
25+
);
26+
}

‎src/components/InstallMCPButton.module.css‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.wrapper {
2+
display: flex;
3+
justify-content: center;
4+
align-items: center;
5+
color: var(--ifm-color-content);
6+
}
7+
8+
.button {
9+
width: fit-content;
10+
display: inline-flex;
11+
align-items: center;
12+
height: 3rem;
13+
14+
display: flex;
15+
align-items: center;
16+
border-radius: 8px;
17+
border: 1px solid var(--color-Neutral_SeparatorSubtle);
18+
background-color: var(--color-Neutral_BackgroundMuted);
19+
20+
cursor: pointer;
21+
transition: background-color 0.2s ease-in-out;
22+
23+
&:hover {
24+
background-color: var(--color-Neutral_BackgroundMuted);
25+
}
26+
}
27+
28+
.label {
29+
height: 100%;
30+
display: flex;
31+
align-items: center;
32+
padding-right: 0.8rem;
33+
min-width: 9.3rem;
34+
35+
/* prevents font size glitch when loading the page */
36+
margin: 0px;
37+
font-size: 1.4rem;
38+
font-weight: 400;
39+
font-family: Inter, sans-serif;
40+
}
41+
42+
.button:hover {
43+
background-color: var(--color-Neutral_BackgroundMuted);
44+
color: var(--ifm-color-content);
45+
}
46+
47+
.iconWrapper {
48+
display: flex;
49+
align-items: center;
50+
justify-content: center;
51+
padding-left: 0.8rem;
52+
padding-right: 0.4rem;
53+
height: 100%;
54+
}

‎src/components/PromptButton.jsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import React, { useEffect, useRef, useState } from 'react';
22

3-
import { QUICK_START_PROMPT } from '../utils/ai-prompts';
3+
import { QUICK_START_PROMPT } from '../utils/quick-start-prompt';
44
import styles from './PromptButton.module.css';
55

66
export default function PromptButton({ prompt = QUICK_START_PROMPT, title = 'Use pre-built prompt to get started faster.' }) {
@@ -56,7 +56,7 @@ export default function PromptButton({ prompt = QUICK_START_PROMPT, title = 'Use
5656
className={styles['toggle-button']}
5757
onClick={togglePrompt}
5858
>
59-
{showPrompt ? 'Hide the prompt' : 'Show the prompt'}
59+
{showPrompt ? 'Hide prompt' : 'Show prompt'}
6060
</button>
6161
<button
6262
className={`${styles['copy-button']} ${copied ? styles.copied : ''}`}

‎src/components/PromptButton.module.css‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
}
1515

1616
/* Apply margin-bottom only when the next sibling is not a heading */
17-
.prompt-card:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)) {
17+
.prompt-card:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)), .full-prompt-container:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)) {
1818
margin-bottom: var(--ifm-leading);
1919
}
2020

@@ -85,7 +85,6 @@
8585
.copy-button:hover {
8686
background: var(--ifm-color-primary-darker);
8787
border-color: var(--ifm-color-primary-darker);
88-
transform: translateY(-1px);
8988
}
9089

9190
.copy-button:active {
@@ -128,13 +127,25 @@
128127
.toggle-button:hover {
129128
background: var(--ifm-color-primary);
130129
color: var(--ifm-color-primary-contrast-background);
131-
transform: translateY(-1px);
132130
}
133131

134132
.toggle-button:active {
135133
transform: translateY(0);
136134
}
137135

136+
/* Dark theme: make secondary button appear as white pill with dark text */
137+
html[data-theme='dark'] .toggle-button {
138+
background: #ffffff;
139+
color: #111827; /* nearly black for contrast */
140+
border-color: #e5e7eb; /* subtle gray border */
141+
}
142+
143+
html[data-theme='dark'] .toggle-button:hover {
144+
background: #f8fafc; /* slight hover tint, keep white look */
145+
color: #111827;
146+
border-color: #d1d5db;
147+
}
148+
138149
.full-prompt {
139150
margin-top: 1.2rem;
140151
padding: 1.2rem;

0 commit comments

Comments
 (0)