Signal Page / AI Productivity
What is a skill doc — and why your AI needs one?
A skill doc is the difference between AI that sounds like you and AI that sounds like everyone else. Here's what they are, why they work, and how to build one in 30 minutes.
A skill doc (also called a system prompt, AI brief, or instruction layer) is a plain-text document that tells an AI tool who it's working for, how it should work, and what rules apply — before any task begins. It's persistent context that lives outside the conversation, uploaded or pasted once, so the AI doesn't need to be re-briefed every time.
Raw AI is generic. It doesn't know how you work.
Every AI tool you use — ChatGPT, Copilot, Claude, Gemini — starts every conversation knowing nothing about you. It doesn't know your brand guidelines, your team's voice, your compliance requirements, or your output format preferences. That's not a flaw. It's the default state of a general-purpose tool.
The result is that most teams end up doing two things on every AI request: explaining context they've explained a hundred times before, and then fixing output that didn't account for things the AI couldn't know. The quality of what you get is directly proportional to the quality of context you provide. Most people provide none.
Repetitive briefing
Same rules, same tone guidance, same format preferences — explained from scratch every conversation.
Inconsistent output
Two people on the same team using the same AI for the same task get meaningfully different results.
Constant rework
Good ideas buried under wrong tone, wrong format, or missing compliance requirements that weren't specified.
What a skill doc actually contains
A skill doc is plain text — no special syntax, no formatting required. It lives in a file, a note, or just in your clipboard. What it contains is structured knowledge about a specific task or role. The AI reads it before doing anything else.
The best skill docs have four components. Each answers a question the AI would otherwise have to guess at.
Role & Context
Who is the AI playing? For whom? In what context? This frames every decision that follows. Without it, the AI defaults to a generic helpful assistant — which is almost never what you want.
Voice & Tone Rules
Reading level, banned words, required phrases, stylistic constraints. This is where brand voice gets encoded as instruction rather than example. Examples are useful too — include them when you can.
Formatting & Structure
Output length, structure, required sections, placeholders, field limits. The AI shouldn't have to guess what a finished draft looks like. Describe it explicitly.
Workflow & Output
What to do first, what to ask for if something is unclear, how to flag potential issues. Turns the AI from a generator into a collaborator with a defined process.
A skill doc isn't a prompt. A prompt is a one-time request. A skill doc is persistent knowledge — it shapes every output that comes after it without you having to ask again.
A pharma email campaign skill doc
Here's a real example: a skill doc written for AI-assisted pharmaceutical email campaigns. It encodes brand voice, compliance requirements, format rules, and workflow into a single reusable document. Click each section to expand.
The pharma context isn't the point. The structure is. Role, voice, format, workflow — the same four components work for a status report, a sales email, a client brief, or a content calendar. The task changes; the pattern holds.
Without vs. with a skill doc
The gap between raw AI and skill-doc-equipped AI isn't marginal. It's the difference between a new intern and someone who's been properly onboarded.
"Write me an email for our knee pain drug for doctors. Make it professional. Oh and we can't say 'best' or 'cure.' Keep it under 300 words. Also include safety info. And make the subject line short. Actually can you also..."
"Write an HCP email for Zilretta. Goal: drive sample requests."
How to write your first skill doc — in 30 minutes
Pick one task your team uses AI for regularly. Something with clear rules and a recognizable output format. That's your first skill doc. Here's the process.
Name the role
Start with: "You are a [role] for [organization/brand]." Be specific. "Email marketing specialist for pharma brands" beats "marketing assistant."
Write the rules you enforce manually
Every time you edit AI output, you're enforcing a rule. Write those rules down. Banned words, required phrases, tone adjectives, things that always get flagged — all of it goes in.
Describe the output
What does a good finished draft look like? Word count, structure, sections, format. If you have a template, describe it. If you have a good example, paste it in and say "like this."
Define the workflow
What should the AI do first? What should it ask if something is unclear? Are there things it should flag before proceeding? Step numbers help — they make the process auditable.
Test it and iterate
Give it a real task. See where the output breaks. Add a rule. Run it again. A skill doc is a living document — the first draft is never the best one. Update it when you catch yourself editing AI output for the same reason twice.
The same file works in any AI tool — Claude, ChatGPT, Copilot, Gemini. Paste it at the start of the conversation, or load it as a system prompt if the interface allows. One doc, every tool.
Brand Voice Guide
Tone, terminology, do's and don'ts for a specific brand or client
Compliance Pre-Flight
Rules for flagging claims, required disclaimers, format requirements for regulated industries
Status Report Format
Your team's preferred structure, metrics, stakeholder audience, and distribution list
Brief Interpreter
How to read a client brief, extract requirements, identify gaps, and ask the right clarifying questions
Email Campaign Builder
Subject lines, preview text, body structure, format rules, compliance checkpoints
Meeting Notes → Actions
How your team formats notes, assigns owners, and tracks follow-ups from meeting transcripts
The open questions
Skill docs work. The pattern is solid. But a few things are still being worked out in practice:
Version control. When the brand voice changes, or a compliance rule gets updated, who updates the skill doc — and how does that version get distributed to the team? Most organizations don't have a good answer for this yet.
Context window limits. Very detailed skill docs can eat into the space available for actual content. The right level of specificity versus brevity depends on the tool and the task — and varies in ways that aren't always obvious until you hit the ceiling.
Skill docs vs. fine-tuning vs. RAG. For teams doing this at real scale, the question of whether a skill doc is the right mechanism or whether something like retrieval-augmented generation is more appropriate is genuinely open. A skill doc is always the faster starting point. It's not always the right endpoint.
How do you know when one is working? The feedback loop is mostly qualitative right now — people notice when they stop having to re-edit the same things. Measuring AI output quality at the team level in a rigorous way is still an unsolved problem for most organizations.