You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This folder contains all STX Halo™ playbooks—step-by-step guides for AI development tasks.
3
+
4
+
## Design Principles
5
+
6
+
**A playbook is not a setup guide.** Users should feel accomplished when they finish. They should feel they learned something meaningful, built something real, and can't wait to explore further.
7
+
8
+
### Core Guidelines
9
+
10
+
1.**Create a moment of success.** Users should *see something happen*: an image appears, a model responds, a server comes alive.
11
+
2.**Teach, don't just instruct.** Explain *why* things work, not just which buttons to click.
12
+
3.**Spark curiosity.** End with "Next Steps" that open doors to further exploration.
13
+
4.**Respect the reader.** Be concise, be clear, and trust them to follow along.
14
+
15
+
### Reference Example
16
+
17
+
See `playbooks/core/comfyui-image-gen/README.md` for a well-structured playbook that demonstrates these principles. See [Previewing](#previewing) to view it in the browser.
18
+
19
+
---
4
20
5
21
## Folder Structure
6
22
@@ -12,35 +28,75 @@ playbooks/
12
28
└── README.md # This file
13
29
```
14
30
15
-
Each playbook lives in its own folder with two required files:
31
+
Each playbook lives in its own folder:
16
32
17
33
```text
18
34
playbook-name/
19
35
├── playbook.json # Metadata (required)
20
36
├── README.md # Content (required)
37
+
├── platform.md # Platform configurations (required for core, optional for supplemental)
21
38
└── assets/ # Images and files (optional)
22
-
└── screenshot.png
23
39
```
24
40
41
+
42
+
### Assets
43
+
44
+
Reference images using relative paths:
45
+
46
+
```markdown
47
+
48
+
```
49
+
50
+
- Max 500 KB per file
51
+
- Formats: PNG, JPEG, GIF, WebP, SVG
52
+
- Include screenshots at key UI moments
53
+
25
54
---
26
55
27
-
## The `assets/` Folder
56
+
## The `README.md` File
57
+
58
+
Write your playbook content in Markdown format. Images, tables, code, and other elements are supported.
59
+
60
+
**Recommended structure:**
28
61
29
-
Playbooks can include an optional `assets/` folder for images and other files referenced in the README.
62
+
| Section | Content |
63
+
|---------|---------|
64
+
|**Overview**| What is this tool? Why is it exciting? (2-3 sentences) |
65
+
|**What You'll Learn**| 3-5 concrete outcomes |
66
+
|**Getting Started**| First hands-on step—get users into the tool quickly |
67
+
|**Core Concepts**| Teach the mental model (tables and diagrams help) |
68
+
|**Main Activity**| Where users achieve the payoff moment |
69
+
|**Next Steps**| 3-5 paths forward with links to resources |
30
70
31
-
### Usage
71
+
### OS-Specific Content
32
72
33
-
Reference assets in your README using relative paths:
73
+
Use HTML comments to mark platform-specific sections:
34
74
35
75
```markdown
36
-
76
+
<!-- @os:windows -->
77
+
Windows-only content
78
+
<!-- @os:end -->
79
+
80
+
<!-- @os:linux -->
81
+
Linux-only content
82
+
<!-- @os:end -->
37
83
```
38
84
39
-
### Requirements
85
+
Content outside `@os` tags is always shown. Keep blocks focused—only tag the parts that differ.
86
+
87
+
### Writing Tips
40
88
41
-
-**Maximum file size**: 500 KB per asset
42
-
-**Supported formats**: PNG, JPEG, GIF, WebP, SVG
43
-
- Use descriptive filenames (e.g., `step1-output.png` instead of `image1.png`)
89
+
- List prerequisites upfront. Don't surprise users mid-playbook
90
+
- Include expected output so users know what success looks like
91
+
- Keep code blocks copy-friendly (avoid `$` or `>` prompts)
92
+
93
+
---
94
+
95
+
## The `platform.md` File
96
+
97
+
Documents pre-installed software, model paths, and platform-specific prerequisites. **Required for `core` playbooks**, since they assume dependencies are preinstalled on the system. Optional for `supplemental` playbooks.
98
+
99
+
See `playbooks/core/comfyui-image-gen/platform.md` for an example.
44
100
45
101
---
46
102
@@ -58,223 +114,40 @@ All playbook folders have already been created. To edit a playbook:
58
114
59
115
## The `playbook.json` File
60
116
61
-
This file contains all metadata for your playbook:
62
-
63
117
```json
64
118
{
65
119
"id": "my-playbook",
66
120
"title": "My Playbook Title",
67
-
"description": "A brief description shown on the playbook card",
121
+
"description": "Brief description for the card (100-150 chars)",
|`platforms`| Yes |`["windows"]`, `["linux"]`, or `["windows", "linux"]`|
137
+
|`published`| Yes | Set `true` to show on website |
138
+
|`difficulty`| No |`"beginner"`, `"intermediate"`, or `"advanced"`|
139
+
|`isNew`| No | Shows "New" badge |
140
+
|`isFeatured`| No | Displays prominently at top |
141
+
|`tags`| No | Keywords for filtering |
127
142
128
143
---
129
144
130
-
## OS-Specific Content
131
-
132
-
When instructions differ between Windows and Linux, use special HTML comments to mark platform-specific sections. The website will filter content based on the user's selected platform.
133
-
134
-
### Syntax
145
+
## Previewing
135
146
136
-
Use these tags to wrap OS-specific content:
137
-
138
-
<!-- @os:windows -->
139
-
Content shown only on Windows
140
-
<!-- @os:end -->
141
-
142
-
<!-- @os:linux -->
143
-
Content shown only on Linux
144
-
<!-- @os:end -->
145
-
146
-
<!-- @os:all -->
147
-
Content shown on all platforms (useful inside a platform block)
148
-
<!-- @os:end -->
149
-
150
-
### Example
151
-
152
-
Here's how to write installation instructions that differ by platform:
0 commit comments