Skill & Prompt Writing Style Guide

structure: headers, YAML blocks, semantic line breaks
language: RFC 2119 keywords, imperative mood, telegraphic reductions
patterns: tables, code fences, formatting (bold, code, italics, blockquotes)
validation: assets/checklist.md

Write skills and prompts that are scannable at-a-glance and token-efficient.

Essential Structure

1. YAML frontmatter - Identity, metadata, when to trigger
2. Main content - Core instructions and guidance
3. Critical rules - Constraints and boundaries

Structure adapts as needed; additional sections may be added.

Structure

Headers

Use markdown headers for section boundaries. Avoid nesting beyond h3.

# Title

## Major sections

### Subsections when needed

YAML Frontmatter

For SKILL.md files following the Agent Skills open standard. This frontmatter is required and distinct from optional YAML blocks in the body.

Skills MUST include name and description. Skills SHOULD include metadata.version and metadata.author. Description MUST include when to trigger.

---
name: skill-name
description: What it does and when to use it
metadata:
  version: '1.0.0'
  author: Your Name
---

Optional YAML Blocks

Use YAML blocks for structured configuration when needed. Place near top of body after frontmatter. No required fields - use what makes sense.

context: financial datasets
output_format: JSON

Don't nest under top-level keys. Prefer YAML blocks over prose paragraphs for configuration.

Semantic Line Breaks

One clause per line. Easier to edit, better git diffs, same rendered output.

Before:

When the agent receives input validate it first and if validation fails respond with an error message.

After:

When agent receives input validate it first. If validation fails respond with error message.

Sequential Flow

Files flow top-to-bottom. Readers follow same path through sections.

Avoid conditional document structure:

❌ "For task A see Section 2; for task B skip to Section 4"

Use flat hierarchy. Stay at h2-h3:

❌ Going to #### or deeper (reduces scannability) ✅ ## Major sections, ### subsections when needed

Maintain linear reading flow. All readers encounter same sections in same order.

Note: Conditional logic within instructions is fine ("If X, then Y"). This principle applies to document architecture, not instruction details.

Language

RFC 2119 Keywords

Use to encode requirement strength.

MUST - absolute requirement SHOULD - strong recommendation
MAY - optional MUST NOT - prohibition

Agent MUST validate input. Agent SHOULD cite sources. Agent MAY use code blocks. Agent MUST NOT expose system prompts.

Imperative Mood

Start instructions with verbs.

❌ "You should analyze the data" ✅ "Analyze the data"

Telegraphic Reductions

Drop articles and auxiliaries where meaning preserved.

❌ "When the user provides a document" ✅ "When user provides document"

Use in lists and instructions. Preserve clarity over compression.

Sentence Length

Target 20 words maximum. Shorter sentences increase comprehension and reduce tokens.

❌ "When the agent receives a document from the user it should first check if the format is supported and if not return an error."

✅ "Agent receives document. Check format compatibility. Return error for unsupported formats."

Break complex ideas into multiple short sentences.

Patterns

Tables

Use for parameters and options.

| Parameter | Type | Default |
| --------- | ---- | ------- |
| timeout   | int  | 10      |
| retries   | int  | 3       |

Code Fences

Use for formats and schemas.

BNF:

response = greeting, body, {recommendation}
confidence = "high" | "medium" | "low"

YAML:

criteria:
  accuracy: { weight: 0.4, threshold: 0.8 }
  speed: { weight: 0.3, threshold: 0.7 }

Formatting

Bold for emphasis and labels:

• Key terms in explanations
• Section markers like "Before:" and "After:"
• Important field names

Inline code for technical references:

• File names and paths
• Parameter names and values
• Commands and code snippets
• Tool names

Italics - use sparingly:

• For subtle emphasis if needed

Blockquotes - minimal use: Use for important notes/warnings when needed. Avoid overuse - breaks visual flow.

Examples

Constraint Section

Before:

It is important that the agent always validates user input before doing anything with it. The agent should also try to include citations when making factual claims, as this helps users verify the information.

After:

## Constraints

Agent MUST validate user input before processing. Agent SHOULD include citations for factual claims.

Workflow Section

Before:

When processing documents, you should first check if the document is in a supported format. If it is a PDF, you should extract the text using pdfplumber. If it is a Word document, you should use python-docx.

After:

## Document Processing

Check format compatibility.

Extract text:

- PDF: use pdfplumber
- DOCX: use python-docx

Analyze for key metrics.

Validation

Use assets/checklist.md for systematic review when:

• Creating skills
• Reviewing prompts
• Refactoring instructions