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:
- Content Templates - Structural templates for Jekyll content
- 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?
- No file clutter
- Attached to commits
- Searchable history
- AI-assisted drafting
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
- Build anticipation
- Ask question related to topic
- Don’t reveal too much ```
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
- Clear Purpose Statement
- What is this template for?
- When should it be used?
- Constraints Section
- Character limits
- Required elements
- Forbidden elements
- Example Output
- Complete, realistic example
- Demonstrates all features
- Variable Documentation
- List all variables
- Explain data sources
- Show expected formats