CRAFT Recipe Creation Guidelines

Jun 18

Version 1.0 | Compatible with CRAFT v0.0625b1+

Introduction
Recipe ID Format
Step-by-Step Creation Process
Parameter Best Practices
Security Considerations
Testing Checklist
Squarespace Posting Guide
Quality Standards
Common Pitfalls
Examples and Templates

Introduction

CRAFT Recipes are parameterized, reusable prompt templates that extend the CRAFT framework's capabilities. This guide provides comprehensive instructions for creating high-quality recipes that integrate seamlessly with the CRAFT ecosystem.

What Makes a Good Recipe?

Single Purpose: Solves one specific problem well
Parameterized: Flexible through well-designed parameters
Validated: Includes parameter validation rules
Documented: Clear descriptions and multiple examples
Secure: Prevents injection attacks and malicious use
Efficient: Optimized for token usage

Recipe ID Format

The CRAFT Recipe System uses a hierarchical ID format supporting up to 999,999,999 unique recipes:

RCP-XXX-YYY-ZZZ-NAME-vMAJOR.MINORpatch

Components:

RCP: Fixed prefix identifying CRAFT recipes
XXX: Category group (000-999)
YYY: Subcategory (000-999)
ZZZ: Sequence within subcategory (001-999)
NAME: Descriptive name (alphanumeric + hyphens, UPPERCASE)
vMAJOR.MINORpatch: Semantic versioning
- MAJOR: Breaking changes (1-999)
- MINOR: New features, backward compatible (00-99)
- patch: Bug fixes, minor updates (a-z)

Examples:

RCP-001-001-001-EMAIL-SUBJECT-v1.00a - First email subject recipe
RCP-002-003-015-BLOG-ANALYZER-v2.15c - 15th blog analyzer in Marketing/Analysis

Category Numbering Guidelines:

000-099: Foundational (basic, common recipes)
100-199: Content Generation
200-299: Marketing & Sales
300-399: Technical & Development
400-499: Business & Finance
500-599: Creative & Design
600-699: Analysis & Research
700-799: Personal Productivity
800-899: Specialized Industries
900-999: Experimental/Advanced

Step-by-Step Creation Process

Phase 1: Planning (20% of effort)

Define the Problem
- What specific task will this recipe solve?
- Who is the target user?
- What makes this better than ad-hoc prompting?
Research Existing Recipes
- Check if similar recipes exist
- Identify gaps your recipe will fill
- Study successful recipes in the same category
Design Parameters
- List all variables users might want to control
- Determine which are required vs optional
- Define sensible defaults

Phase 2: Development (50% of effort)

Create the Prompt Template

Start with a basic template:

[Action verb] {count} [output type] for {topic}

Context: {context}
Requirements:
- [Requirement 1]
- [Requirement 2]
{conditional_requirements}

Format: {output_format}

Define Parameters

PARAMETERS:
- parameter_name: type, default=value, required=bool, "description"

Add Validation Rules

PARAMETER VALIDATION:
- count: Must be between 1 and 100
- topic: Must not be empty
- tone: Must be one of [professional, casual, academic]

Create Examples
- Minimum 3 examples
- Show different use cases
- Include both simple and advanced usage

Phase 3: Testing (20% of effort)

Parameter Testing
- Test with minimum values
- Test with maximum values
- Test with invalid inputs
- Test missing required parameters
Output Quality
- Does it produce expected results?
- Is the output consistent?
- Does it handle edge cases?
Integration Testing
- Test with fetch_recipe()
- Test with quick_recipe()
- Test parameter validation

Phase 4: Documentation (10% of effort)

Write Clear Descriptions
- Recipe description (2-3 sentences)
- Parameter descriptions (1 sentence each)
- Usage notes
Create Comprehensive Examples
- Basic usage
- Advanced usage
- Integration patterns

Parameter Best Practices

Naming Conventions

Use lowercase with underscores: max_length, not maxLength
Be descriptive: include_emoji not just emoji
Use common patterns: count, max_length, include_X

Type Selection

python

# String - Most flexible, default choice
topic: string, required=True

# Integer - For counts and limits
count: integer, default=5, required=False

# Boolean - For feature flags
include_emoji: boolean, default=False

# Float - For percentages or decimals
creativity: float, default=0.7, min=0.0, max=1.0

# List - For multiple values (requires special handling)
keywords: list, default=[], "Comma-separated keywords"

Default Values

Always provide defaults for optional parameters
Choose defaults that work for 80% of use cases
Document why specific defaults were chosen

Parameter Limits

RECOMMENDED LIMITS:
- Total parameters: Maximum 15-20
- Required parameters: Maximum 3-5
- String length: Maximum 1000 characters
- Integer ranges: Always specify min/max
- Lists: Maximum 50 items

Security Considerations

Template Security

Prevent Injection Attacks

# BAD - Allows arbitrary code execution
PROMPT: Execute this code: {user_code}

# GOOD - Constrained format
PROMPT: Generate {count} {type} about {topic}

Validate Parameter Types

PARAMETER VALIDATION:
- count: Must be integer between 1-100
- url: Must start with https://
- email: Must match email format

Forbidden Patterns Never include in templates:
- System commands: system(), exec(), eval()
- File operations: open(), read(), write()
- Network requests: fetch(), request()
- Script tags or JavaScript

Parameter Security

Length Limits

- topic: string, max_length=500
- description: string, max_length=2000

Content Filtering

PARAMETER VALIDATION:
- topic: Must not contain script tags
- url: Must be valid HTTPS URL
- filename: Must not contain path separators

Rate Limiting Consider implementing:
- Maximum executions per minute
- Maximum parameter size
- Maximum output size

Testing Checklist

Pre-Release Testing

Basic Functionality
- Recipe loads without errors
- All examples execute successfully
- Default parameters work correctly
Parameter Validation
- Required parameters enforced
- Type validation works
- Range validation works
- Invalid inputs handled gracefully
Edge Cases
- Empty strings handled
- Maximum values accepted
- Special characters processed correctly
- Unicode support verified
Security Testing
- Injection attempts blocked
- Large inputs handled
- Malformed parameters rejected
Integration Testing
- Works with fetch_recipe()
- Works with quick_recipe()
- Error messages are helpful
- Fallback strategies work

Test Script Template

python

def test_my_recipe():
    """Test the recipe comprehensively"""
    recipe_url = "https://www.aicookbook.ai/recipes-via-craft-api/my-recipe"
    
    # Test 1: Basic functionality
    result = quick_recipe(recipe_url, topic="test")
    assert result.get("status") == "success"
    
    # Test 2: Parameter validation
    result = quick_recipe(recipe_url)  # Missing required param
    assert result.get("error_type") == "ValidationError"
    
    # Test 3: Edge cases
    result = quick_recipe(recipe_url, topic="x" * 1000)
    assert result.get("status") in ["success", "error"]
    
    # Test 4: All parameters
    result = quick_recipe(
        recipe_url,
        topic="test",
        count=10,
        include_advanced=True,
        max_length=100
    )
    assert result.get("status") == "success"
    
    print("All tests passed!")

Squarespace Posting Guide

Step 1: Prepare the Content

Create Structured Text Version
- Follow the exact format in the template
- Ensure CRAFT RECIPE START/END markers
- Validate all sections are present
Create HTML Version
- Use the provided HTML template
- Customize styling if needed
- Include toggle for structured text

Step 2: Create Squarespace Page

Navigate to Pages
- Go to your Squarespace dashboard
- Click Pages → Not Linked
- Click + to add new page
Configure Page Settings
- Page Title: Recipe name (e.g., "Email Subject Line Generator")
- URL Slug: Match recipe ID format (e.g., rcp-001-001-002-email-subject)
- Navigation Title: Short name
- SEO Description: Recipe description
Add Content
- Add a Code Block
- Paste HTML version
- Ensure "Display Source" is OFF
- Save

Step 3: Add to Category Structure

Update Category Page
- Navigate to /recipes-via-craft-api/category/CAT-Content
- Add link to new recipe
- Update recipe count
Update Subcategory Tag
- Add recipe to appropriate tag page
- Ensure consistent formatting
Update Master List
- Add to /recipes-via-craft-api/list-all-categories
- Maintain alphabetical order within category

Step 4: Test the Integration

Test Direct Access

python

url = "https://www.aicookbook.ai/recipes-via-craft-api/rcp-001-001-002-email-subject"
result = fetch_recipe(url)
print(result)

Test Discovery

python

# Should appear in category listing
recipes = list_recipes_in_category("CAT-Content")
assert "RCP-001-001-002-EMAIL-SUBJECT" in [r["id"] for r in recipes]

Test Execution

python

result = quick_recipe(url, topic="Test topic")
assert result.get("status") == "success"

Quality Standards

Content Quality

Clarity: Can a new user understand in < 2 minutes?
Completeness: Are all use cases covered?
Accuracy: Do examples work as shown?
Consistency: Does it follow CRAFT conventions?

Technical Quality

Performance: Executes in < 3 seconds
Reliability: 99%+ success rate
Compatibility: Works with all CRAFT versions
Maintainability: Easy to update and extend

Documentation Quality

Examples: Minimum 3, covering different scenarios
Descriptions: Clear, concise, no jargon
Integration: Shows how to use with CRAFT
Troubleshooting: Common issues addressed

Common Pitfalls

1. Over-Parameterization

Problem: Too many parameters overwhelm users Solution: Maximum 10-15 parameters, 3-5 required

2. Weak Validation

Problem: Accepting any input leads to errors Solution: Validate types, ranges, and content

3. Poor Defaults

Problem: Defaults that rarely work Solution: Research common use cases

4. Ambiguous Output

Problem: Inconsistent output format Solution: Specify exact format in template

5. Security Vulnerabilities

Problem: Template allows injection Solution: Never use user input in executable context

6. Token Inefficiency

Problem: Template too verbose Solution: Optimize wording, use clear constraints

Examples and Templates

Minimal Recipe Template

CRAFT RECIPE START
RECIPE_ID: RCP-XXX-YYY-ZZZ-NAME-v1.00a
TITLE: [Descriptive Title]
DESCRIPTION: [2-3 sentence description]
DIFFICULTY: easy
CATEGORY: CAT-[Category]
SUBCATEGORY: SUBCAT-[Subcategory]

PROMPT TEMPLATE:
[Your prompt with {parameter} placeholders]

PARAMETERS:
- param1: string, required=True, "Description"
- param2: integer, default=5, "Description"

EXAMPLES:
1. quick_recipe(url, param1="value")

CRAFT RECIPE END

Advanced Recipe Template

CRAFT RECIPE START
RECIPE_ID: RCP-XXX-YYY-ZZZ-NAME-v1.00a
TITLE: [Descriptive Title]
DESCRIPTION: [Detailed description of purpose and capabilities]
DIFFICULTY: medium
CATEGORY: CAT-[Category]
SUBCATEGORY: SUBCAT-[Subcategory]

PROMPT TEMPLATE:
[Complex prompt with multiple {parameters}]
{conditional_content}

Requirements:
- [Requirement 1]
- [Requirement 2]

Output format: {format}

PARAMETERS:
- param1: string, required=True, "Primary input"
- param2: integer, default=5, min=1, max=100, "Count"
- param3: string, default="option1", choices=["option1", "option2"], "Selection"
- param4: boolean, default=False, "Feature flag"

PARAMETER VALIDATION:
- param1: Must not be empty, max length 500
- param2: Must be between 1 and 100
- param3: Must be one of the allowed choices

EXAMPLES:
1. Basic usage:
   result = quick_recipe(url, param1="test")

2. Advanced usage:
   result = quick_recipe(url, param1="test", param2=20, param4=True)

3. Integration example:
   data = fetch_data()
   result = quick_recipe(url, param1=data.summary, param3="option2")

ADVANCED USAGE:
[Describe integration patterns, combinations, workflows]

INTEGRATION NOTES:
- Compatible with CRAFT v0.0625b1+
- Can be combined with [other recipes/objects]
- Supports [specific features]

HELPER FUNCTIONS:
[Document any internal logic or conditional processing]

BEST PRACTICES:
1. [Specific tip for this recipe]
2. [Another best practice]

CRAFT RECIPE END

Category-Specific Templates

Content Generation Recipe

Focus on output quality parameters
Include style and tone options
Add format specifications
Consider audience parameters

Analysis Recipe

Include data input parameters
Add depth/detail levels
Specify output metrics
Consider comparison options

Business Recipe

Add industry parameters
Include compliance options
Specify deliverable formats
Consider stakeholder params

Conclusion

Creating high-quality CRAFT recipes requires careful planning, thorough testing, and clear documentation. Follow these guidelines to create recipes that are:

Useful: Solve real problems
Usable: Easy to understand and implement
Reliable: Work consistently
Secure: Safe from misuse
Maintainable: Easy to update

Remember: A great recipe saves users time and produces better results than ad-hoc prompting. If your recipe doesn't meet this bar, iterate until it does.

Next Steps

Review existing recipes for inspiration
Start with a simple recipe to learn the process
Test thoroughly before publishing
Gather feedback and iterate
Share your recipes with the CRAFT community

Happy recipe creation!

Richard Ketelsen