Skip to main content
This guide walks through a complete workflow: creating a new prompt package, publishing it to the registry, installing it in another project, and running it with variables.

​
Overview

A typical prompt development workflow involves:
1

Authenticate

Login to the Prompts.dev platform
2

Create

Initialize a new prompt package with the required structure
3

Develop

Write your prompt template and configure metadata
4

Publish

Upload your package to the registry
5

Distribute

Install and use the prompt in your projects

​
Complete example

Let’s create a prompt for generating API documentation from code.

​
1. Authentication

First, authenticate with GitHub: 
prompt login
This opens your browser for OAuth authentication. Once complete, your token is stored in ~/.prompts/config.json (see main.go:395-403).
You can also use --provider google for Google OAuth (see main.go:155).

​
2. Create package structure

Initialize a new prompt package: 
prompt init api-doc-generator
This creates the following structure: 
api-doc-generator/
├── prompt.yaml
├── prompt.md
└── README.md

​
3. Configure the manifest

Edit prompt.yaml to define your prompt’s metadata and required inputs:
prompt.yaml
name: api-doc-generator
description: Generate comprehensive API documentation from code
version: 1.0.0
author: topboyasante
inputs:
  - name: language
    required: true
  - name: code
    required: true
  - name: style
    required: false
tags:
  - documentation
  - api
  - code-generation
The manifest must include name and version fields for publishing (see main.go:417-425).

​
4. Write the prompt template

Edit prompt.md to create your prompt with variable placeholders:
prompt.md
You are an expert technical writer specializing in API documentation.

Generate comprehensive API documentation for the following \{\{language\}\} code:

\`\`\`\{\{language\}\}
\{\{code\}\}
\`\`\`

Documentation requirements:
- Clear description of the API's purpose
- Parameter descriptions with types
- Return value documentation
- Example usage with realistic data
- Error handling information
- Follow \{\{style\}\} documentation style (if provided)

Provide the documentation in Markdown format.
The CLI uses simple {{variable}} syntax for template variables (see main.go:326-329).

​
5. Document your prompt

Update README.md with usage instructions:
README.md
# API Documentation Generator

Generate comprehensive API documentation from code snippets.

## Inputs

- `language` (required): Programming language of the code
- `code` (required): The code to document
- `style` (optional): Documentation style guide to follow

## Example

```bash
prompt run api-doc-generator \
  --var language=python \
  --var code="def add(a, b): return a + b" \
  --var style="Google Python Style Guide"

​
Tags

  • documentation
  • api
  • code-generation

### 6. Publish to registry

Publish your prompt package:

```bash
cd api-doc-generator
prompt publish
The CLI will:
  1. Validate your prompt.yaml manifest (see main.go:209-211)
  2. Create a tarball of your package (see main.go:226-230)
  3. Upload it to the registry (see main.go:236-238)
Expected output: 
Published [email protected]

​
7. Install in another project

Now you can install and use your prompt in any project: 
cd ~/my-project
prompt install topboyasante/api-doc-generator
The package is downloaded to .prompts/api-doc-generator/ (see main.go:286). Expected output: 
Installed topboyasante/[email protected] into .prompts/api-doc-generator

​
8. Run the prompt

Render the prompt with your variables: 
prompt run api-doc-generator \
  --var language=python \
  --var code="def calculate_total(items, tax_rate=0.1):\n    subtotal = sum(item['price'] for item in items)\n    return subtotal * (1 + tax_rate)" \
  --var style="Google Python Style Guide"
The CLI validates required inputs (see main.go:318-324) and performs variable substitution (see main.go:326-329). Output: 
You are an expert technical writer specializing in API documentation.

Generate comprehensive API documentation for the following python code:

def calculate_total(items, tax_rate=0.1):
    subtotal = sum(item['price'] for item in items)
    return subtotal * (1 + tax_rate)

Documentation requirements:
- Clear description of the API's purpose
- Parameter descriptions with types
- Return value documentation
- Example usage with realistic data
- Error handling information
- Follow Google Python Style Guide documentation style

Provide the documentation in Markdown format.

​
Publishing updates

To publish a new version:
1

Update version

Increment the version in prompt.yaml:
version: 1.1.0
2

Make changes

Update your prompt template or metadata
3

Publish

prompt publish
Output: Published [email protected]

​
Working with versions

Install specific versions or always get the latest: 
prompt install topboyasante/api-doc-generator
When no version is specified, the CLI fetches the latest from the API (see main.go:270-279).

​
Searching for prompts

Discover prompts created by the community: 
prompt search documentation
Output: 
NAME                    DESCRIPTION
api-doc-generator       Generate comprehensive API documentation from code
code-explainer          Explain code with detailed documentation
doc-reviewer            Review and improve existing documentation
Results are sorted alphabetically (see main.go:353).

​
Best practices

​
Package structure

Each prompt package should solve one specific problem. Instead of a general “code-helper” prompt, create:
  • code-reviewer - Review code for bugs and improvements
  • code-documenter - Generate documentation
  • code-explainer - Explain complex code
Follow semver for versions:
  • 1.0.0 → 1.0.1 - Bug fixes or minor improvements
  • 1.0.0 → 1.1.0 - New features, backward compatible
  • 1.0.0 → 2.0.0 - Breaking changes
Always explain what each input does in your README:
## Inputs

- `language` (required): Programming language of the code (e.g., python, javascript, go)
- `code` (required): The code snippet to document (string)
- `style` (optional): Style guide to follow (e.g., "Google Python Style Guide")
Use descriptive tags to help users find your prompt:
tags:
  - documentation    # Primary purpose
  - api             # Use case
  - python          # Relevant language
  - code-generation # Category
Run your prompt locally before publishing:
# In your package directory
cd api-doc-generator

# Install locally
mkdir -p .prompts/api-doc-generator
cp -r . .prompts/api-doc-generator/

# Test
prompt run api-doc-generator --var language=python --var code="..."

​
Variable naming

❌ Bad:
inputs:
  - name: x
  - name: y
  - name: z
✅ Good:
inputs:
  - name: language
  - name: code
  - name: style
Only mark inputs as required: true if the prompt cannot function without them (see main.go:318-324):
inputs:
  - name: code
    required: true      # Essential
  - name: language
    required: true      # Essential
  - name: style
    required: false     # Optional enhancement

​
Integration examples

Publish prompts automatically:
.github/workflows/publish.yml
name: Publish Prompt
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
          go-version: '1.25'
      - name: Install CLI
        run: go install github.com/topboyasante/prompts/cmd/cli@latest
      - name: Publish
        env:
          PROMPTS_API_URL: ${{ secrets.PROMPTS_API_URL }}
        run: |
          echo '${{ secrets.PROMPTS_TOKEN }}' > ~/.prompts/config.json
          prompt publish
Add prompt commands to package.json:
package.json
{
  "scripts": {
    "prompt:install": "prompt install topboyasante/api-doc-generator",
    "prompt:run": "prompt run api-doc-generator --var language=typescript",
    "docs:generate": "npm run prompt:install && npm run prompt:run"
  }
}
Automate prompt rendering:
generate-docs.sh
#!/bin/bash
set -e

# Install prompt if not present
if [ ! -d ".prompts/api-doc-generator" ]; then
  prompt install topboyasante/api-doc-generator
fi

# Generate docs for all Python files
for file in src/**/*.py; do
  code=$(cat "$file")
  output="docs/$(basename "$file" .py).md"
  
  prompt run api-doc-generator \
    --var language=python \
    --var code="$code" \
    --var style="Google" > "$output"
  
  echo "Generated documentation: $output"
done

​
Troubleshooting

Problem: Login times out after 2 minutes (see main.go:149-151)Solution:
  • Ensure port 9876 is not blocked by firewall
  • Try --provider google if GitHub is blocked
  • Check that your browser isn’t blocking the callback
Problem: error: missing required --var [name]Solution: Check the manifest for required inputs (see main.go:318-324):
cat .prompts/[name]/prompt.yaml
Provide all required variables:
prompt run [name] --var required_field=value
Problem: prompt already exists; fetch prompt id and publish a new versionSolution: You’re trying to publish a prompt with a name that’s already taken (see main.go:223). Either:
  • Choose a different name in prompt.yaml
  • If you own the prompt, increment the version and publish again
Problem: file exists: [path] (use --force to overwrite)Solution: The directory already contains files (see main.go:182-186). Use:
prompt init my-prompt --force

​
Next steps

API Reference

Learn about the underlying REST API

Concepts

Understand core concepts of Prompts.dev

Build docs developers (and LLMs) love

Get started for freeTalk to us