Templates and Prompts Reference

Overview

This document describes all content templates and AI prompts used in the content generation system. Templates are divided into two categories:

  1. Content Templates - Structural templates for Jekyll content
  2. AI Prompts - Instructions for AI-assisted content generation

Directory Structure

├── brands/
│   └── zircote/
│       ├── brand.yml                      # Brand configuration
│       └── templates/
│           ├── blog-post.prompt.md        # Brand-specific blog prompt
│           └── release-notes.prompt.md    # Release notes prompt
│
├── templates/
│   ├── blog-post.md                       # Jekyll blog template
│   ├── social/
│   │   ├── twitter.prompt.md
│   │   ├── linkedin.prompt.md
│   │   ├── bluesky.prompt.md
│   │   └── mastodon.prompt.md
│   └── release/
│       └── release-notes.md
│
├── prompts/
│   ├── blog-to-social.prompt.md
│   ├── video-to-social.prompt.md
│   └── repurpose-content.prompt.md
│
└── schemas/
    ├── blog.schema.yml
    └── social.schema.yml

Brand Configuration

File: brands/zircote/brand.yml

The brand configuration defines voice, audience, and visual identity.

Key Sections

Voice and Tone
voice:
  tone:
    - technical      # Precise, accurate terminology
    - practical      # Focus on real-world application
    - direct         # Clear, no fluff
    - helpful        # Genuinely useful to reader

  personality:
    - knowledgeable  # Subject matter expertise
    - approachable   # Not intimidating
    - efficiency-focused
    - open-minded

  style_guidelines:
    - Write from hands-on experience
    - Show code, not just concepts
    - Explain the "why" behind decisions
    - Be honest about tradeoffs
    - Keep explanations concise but complete
    - Use real examples from actual projects
Target Audience
audience:
  primary:
    - Software architects
    - Backend developers
    - DevOps engineers
    - Open source contributors

  secondary:
    - Tech leads
    - API designers
    - Developer advocates
    - Agriculture tech enthusiasts

  demographics:
    experience_level: intermediate-to-senior
    interests:
      - PHP development
      - Python tooling
      - API design (OpenAPI/Swagger)
      - AI-assisted development
      - Developer productivity
      - Agricultural technology
      - Automation
Content Guidelines
guidelines:
  do:
    - Include working code examples
    - Link to source repositories
    - Show real output and results
    - Explain architectural decisions
    - Provide installation instructions
    - Update content when tools change

  dont:
    - Write without code examples
    - Make claims without evidence
    - Skip error handling in examples
    - Assume reader environment
    - Leave broken links
    - Forget alt text for images

Blog Post Template

File: templates/blog-post.md

---
layout: post
title: ""
date: 
author: Robert Allen
categories: []
tags: []
description: ""
image: /assets/images/blog//.png
canonical_url: https://www.zircote.com/blog////
---

## Introduction







## 






## 



### 



## 



## Key Takeaways

- 
- 
- 

## Next Steps



---

**

Frontmatter Fields

Field Required Description
layout Yes Always post for blog posts
title Yes Post title (50-70 chars for SEO)
date Yes Publication date (YYYY-MM-DD)
author Yes Author name
categories Yes Primary categorization (1-2)
tags No Detailed tags (3-5)
description Yes Meta description (120-160 chars)
image No Featured image path
canonical_url No Canonical URL if cross-posted

AI Prompt Templates

Blog Post Generation Prompt

File: brands/zircote/templates/blog-post.prompt.md

# Blog Post Generation Prompt

## Context

You are writing a blog post for zircote.com, a technical blog focused on
developer tools, AI-assisted development, and agriculture technology.

## Brand Voice

Refer to `brands/zircote/brand.yml` for complete voice guidelines. Key points:
- Technical but accessible
- Practical, hands-on approach
- Direct and efficient
- Show, don't just tell

## Audience

Primary: Senior developers, software architects, DevOps engineers
Secondary: Tech leads, open source contributors

## Post Requirements

**Title**: 
**Target Word Count**: 
**Topics**: 
**Pillar**: 

## Structure

1. **Hook** (100-150 words)
   - Start with a relatable problem or interesting observation
   - Avoid generic openings ("In today's world...")
   - Be specific to the topic

2. **Problem Statement** (100-150 words)
   - Clearly define the problem being solved
   - Explain why existing solutions fall short
   - Connect to reader's experience

3. **Solution Overview** (200-300 words)
   - Introduce your approach
   - Explain why this approach works
   - Set expectations for the rest of the post

4. **Main Content** (800-1200 words)
   - 2-4 major sections
   - Each section should have:
     - Clear heading
     - Explanatory text
     - Code example (if applicable)
     - Practical insight

5. **Code Examples**
   - Real, working code (not pseudocode)
   - Include necessary imports/setup
   - Add comments explaining key parts
   - Show expected output where relevant

6. **Key Takeaways** (3-5 bullets)
   - Actionable insights
   - Not just a summary

7. **Call to Action**
   - Specific next step for reader
   - Link to relevant resource
   - Question to encourage engagement

## Do

- Include working code examples
- Link to repositories
- Explain architectural decisions
- Be honest about tradeoffs
- Use real output/results

## Don't

- Write without examples
- Make unsubstantiated claims
- Skip error handling
- Assume environment setup
- Use placeholder code

## News Integration


This post should incorporate current developments. Include:
- 1-2 recent news items from the topic area
- Brief analysis of their significance
- Connection to the main topic


## Output Format

Provide the complete blog post in markdown format, ready for Jekyll.
Include frontmatter with all required fields.

Social Media Prompts

Twitter/X Prompt

File: templates/social/twitter.prompt.md

# Twitter/X Post Generation

## Constraints

- Maximum 280 characters per tweet
- Thread format: 2-4 tweets for blog promotion
- Include link in final tweet

## Format

**Tweet 1 (Hook)**:
- Lead with the problem or insight
- Create curiosity
- No link yet

**Tweet 2 (Value)**:
- Key insight or takeaway
- Make it quotable
- Self-contained value

**Tweet 3 (CTA + Link)**:
- Brief summary
- Call to action
- Include link

## Example Output

Tweet 1: The problem with ADRs isn’t the concept—it’s the file clutter.

Every architectural decision becomes another markdown file competing for attention.

Tweet 2: What if ADRs lived in git notes instead?

Tweet 3: I built git-adr to make architecture decisions first-class git citizens.

Try it: [link]


## Source Post



## Instructions

Generate a 3-tweet thread promoting this post. Follow the format above.

LinkedIn Prompt

File: templates/social/linkedin.prompt.md

# LinkedIn Post Generation

## Constraints

- Maximum 3000 characters
- Professional but not corporate
- Format for readability (short paragraphs, line breaks)

## Format

**Opening Hook** (1-2 lines):
- Strong statement or question
- Grab attention in feed

**Body** (3-5 short paragraphs):
- Key insights from the post
- Personal perspective
- Actionable takeaways

**Engagement** (1-2 lines):
- Question to prompt discussion
- Not salesy

**Link**:
- Full URL at the end
- Brief description

## Example Output

Every architecture decision we make gets lost in a sea of markdown files.

After years of watching ADRs become write-once documentation that nobody reads, I built something different.

git-adr stores architecture decisions in git notes—attached to commits, searchable, and integrated with your actual development workflow.

Three things that made the difference: → No file clutter in your repo → Decisions linked to the code that implements them → AI-assisted drafting for consistency

The result? Teams actually reference their architectural decisions.

What’s your experience with ADRs? Do they work or become documentation debt?

Full post: [link]


## Source Post



## Instructions

Generate a LinkedIn post promoting this content. Follow the format above.
Professional but conversational tone.

Bluesky Prompt

File: templates/social/bluesky.prompt.md

# Bluesky Post Generation

## Constraints

- Maximum 300 characters per post
- Thread format supported
- More casual than Twitter

## Format

**Single Post** (for straightforward promotion):
- Key insight
- Brief context
- Link

**Thread** (for deeper content):
- Post 1: Hook
- Post 2-3: Key points
- Post 4: CTA + Link

## Tone

- Conversational
- Less polished than LinkedIn
- More personal than Twitter
- Community-focused

## Example Output

finally got around to writing up why I built git-adr

tl;dr: ADR files are clutter, git notes are not

if you’re tired of architecture decisions living in markdown files nobody reads, this might help

[link]


## Source Post



## Instructions

Generate a Bluesky post. Keep it casual and direct.

Transformation Prompts

Blog to Social

File: prompts/blog-to-social.prompt.md

# Blog to Social Media Transformation

## Purpose

Transform a blog post into platform-optimized social media content.

## Input

**Blog Post**: 
**Platforms**: 

## Output Requirements

For each platform, provide:
1. Ready-to-post content
2. Optimal posting time suggestion
3. Hashtag recommendations (where applicable)

## Platform Guidelines

### Twitter/X
- 2-3 tweet thread
- Hook → Value → CTA structure
- Use line breaks for readability
- Hashtags: 1-2 max, at end

### LinkedIn
- 1000-1500 characters
- Professional but personal
- Use line breaks liberally
- No hashtags or minimal

### Bluesky
- 1-2 posts
- Casual, conversational
- Direct language
- No hashtags

### Mastodon
- Up to 500 characters
- Open source community focus
- CW if technical/niche
- Hashtags: 3-5 at end

## Extraction Focus

Pull these elements from the blog post:
1. Core problem being solved
2. Key insight or approach
3. 2-3 takeaways
4. Call to action

## Do Not

- Copy-paste paragraphs directly
- Use the same content across platforms
- Include the full article
- Oversell or use hype language

Video to Social

File: prompts/video-to-social.prompt.md

# Video to Social Media Transformation

## Purpose

Create social media posts to promote video content.

## Input

**Video Title**: 
**Video Description**: 
**Key Moments**: 
**Platform**: 

## Output Format

### Pre-Release (1-2 days before)

Teaser post announcing upcoming video

Release Day

Main promotion post
- Hook with the problem/question
- Brief description
- Link to video
- CTA to watch

Follow-up (2-3 days after)

Engagement post
- Share specific insight from video
- Ask for reactions/questions
- Link for those who missed it

Platform Adjustments

Apply same guidelines as blog-to-social for each platform.


## Schema Validation

### Blog Schema

**File**: `schemas/blog.schema.yml`

```yaml
type: object
required:
  - layout
  - title
  - date
  - author
  - description
properties:
  layout:
    type: string
    enum: [post]
  title:
    type: string
    minLength: 10
    maxLength: 100
  date:
    type: string
    format: date
  author:
    type: string
  categories:
    type: array
    items:
      type: string
      enum:
        - developer-tools
        - ai-development
        - agriculture-tech
        - community
        - api-design
  tags:
    type: array
    items:
      type: string
  description:
    type: string
    minLength: 50
    maxLength: 200
  image:
    type: string
  canonical_url:
    type: string
    format: uri

Social Schema

File: schemas/social.schema.yml

type: object
required:
  - platform
  - content
  - source_url
properties:
  platform:
    type: string
    enum: [twitter, linkedin, bluesky, mastodon]
  content:
    type: string
  source_url:
    type: string
    format: uri
  scheduled_time:
    type: string
    format: date-time
  thread:
    type: array
    items:
      type: string
  hashtags:
    type: array
    items:
      type: string

Template Variables

Common Variables

Variable Source Description
`` Calendar Post title
`` Calendar Brief description
`` Calendar Topic list
`` Calendar Content pillar
`` Calendar Target word count
`` Calendar Publication date
`` Calendar Call to action text
`` Calendar Related repository

Computed Variables

Variable Computed From Description
`` date 4-digit year
`` date 2-digit month
`` date 2-digit day
`` title URL-safe version
`` pillar + topics Category list
`` topics Tag list

Using Templates with AI

Claude Code Example

You have access to these files:
- Brand: brands/zircote/brand.yml
- Template: brands/zircote/templates/blog-post.prompt.md
- Calendar item: (see below)

Calendar Item:
```yaml
title: "The State of AI Coding Assistants in 2026"
description: "Comparing Claude Code, GitHub Copilot, Cursor, and emerging tools"
topics: [ai-development, tools, industry-analysis]
pillar: ai-development
word_count: 2000
cta: "What's your preferred AI coding setup?"
news_integration: true

Generate a complete blog post following the template and brand guidelines.


### GitHub Copilot Example

The GitHub Issue body provides context for Copilot:

```markdown
### For Copilot

Use the following resources:
- Brand voice: `brands/zircote/brand.yml`
- Blog template: `brands/zircote/templates/blog-post.prompt.md`
- Schema: `schemas/blog.schema.yml`

Save draft to: `content/blog/drafts/2026-01-09-ai-coding-assistants.md`

Creating New Templates

Template Naming Convention

{type}.prompt.md      # AI generation prompts
{type}.md             # Structural templates
{type}.schema.yml     # Validation schemas

Template Requirements

  1. Clear Purpose Statement
    • What is this template for?
    • When should it be used?
  2. Constraints Section
    • Character limits
    • Required elements
    • Forbidden elements
  3. Example Output
    • Complete, realistic example
    • Demonstrates all features
  4. Variable Documentation
    • List all variables
    • Explain data sources
    • Show expected formats