DEV Community: AgentOps Lab

context.md vs SKILL.md: Stop Pasting Product Facts Into Every Prompt

AgentOps Lab — Sun, 01 Nov 2026 16:34:21 +0000

By AgentOps Lab

You already know agents work better with instructions. The quieter problem is where those instructions live. If every prompt opens with the same product paragraph—“We’re a B2B tool for mid-market ops teams, friendly but crisp, never invent pricing…”—you are not being thorough. You are paying a copy-paste tax on facts that should live in one file and stay out of the skill.

This post is about separation of concerns: a stable SKILL.md for when / how / done, and a mutable context.md for audience, tone, offers, and constraints that change weekly. It stands alone if you never read another tutorial; if you already installed a skill folder, this is the missing half.

The symptom: the same product paragraph every time

Watch a typical indie founder or PM chat with an agent for a week:

Monday — draft a support reply → paste ICP, plan names, tone rules.
Tuesday — changelog → paste the same block plus “don’t promise dates.”
Wednesday — competitor note → paste again, then add this week’s price.
Thursday — forget one constraint → agent invents a refund policy.

The symptom is not “bad prompting.” It is facts glued into every task. Those facts drift. Prices change. Positioning softens. A must-not rule gets forgotten on a busy day. The skill (or mega-prompt) that embeds last month’s offer starts lying with confidence.

You feel it as friction: longer first messages, inconsistent voice across chats, and a fear of editing the “big prompt” because you might break the process steps that actually still work.

Two files, two jobs

Treat agent ops like code: procedures and configuration are different lifetimes.

File	Job	Change cadence	Example contents
`SKILL.md`	Procedure	Rarely	When to use, goal, steps, done criteria, anti-patterns
`context.md`	Facts	Weekly (or whenever the product moves)	Audience, tone, must-nots, canonical links, current offer

SKILL.md answers: When should this fire? What process do I follow? What does “done” look like?

context.md answers: Who are we talking to? How should we sound? What must we never claim? What is true this week?

The skill should read context, not contain it. That is the whole pattern. Once you feel it, pasting “we’re a B2B tool for…” into every prompt starts to look like hard-coding config into a function body.

What belongs in the skill (and what doesn’t)

Keep the skill thin and durable. A solid SKILL.md usually has:

Trigger / when to use — short phrases the agent can match
Goal — one sentence definition of good
Inputs to collect — ask once if missing (topic, sources, severity…)
Process — 3–5 steps, ordered
Output shape — headings, table, or checklist the human expects
Anti-patterns / hard rules — process-level (don’t invent numbers; don’t auto-send legal replies)

Leave these out of the skill body:

Company or product name (unless the skill is truly product-locked)
ICP paragraphs and persona essays
Exact prices, plan names, coupon codes
This week’s launch angle or waitlist URL
Tone adjectives that change with brand experiments
Metric dashboards and OKR snapshots

If a line would be wrong after a pricing tweak or a repositioning, it belongs in context.md. If a line still makes sense when you fork the skill to a second product, it belongs in SKILL.md.

A useful smell test: Would I reuse this skill on a different product tomorrow? If yes after swapping one context file, you split correctly. If you would rewrite half the skill, you baked facts into procedure.

Minimal `context.md` template

You do not need a novel. Start with a single file at the project root (or beside your skills folder) and keep it under ~40 lines until it hurts.

# Project context (edit weekly)

## Product
- Name:
- One-liner:
- Primary URL:

## Audience
- ICP (who buys / who uses):
- Not for:

## Voice
- Tone (3 adjectives max):
- Words we use:
- Words we avoid:

## Must-not
- Never invent pricing, SLAs, or timelines
- Never claim:
- Escalate to a human when:

## Current offer (update when it changes)
- Plan / price:
- What “free” includes:
- Checkout or waitlist link:

## Canonical links
- Docs:
- Status / changelog:
- Support:

## Notes for agents
- Read this file before drafting customer-facing text.
- If a fact is missing, mark Unknown — do not guess.

That is enough for support drafts, changelogs, outreach, and research briefs aimed at your buyers. Expand sections only when a real miss forces it (e.g. a “known incidents” block during an outage week).

Name variants are fine (saas-context.md, product-context.md). Pick one name per repo and stick to it so every skill can point at the same path.

Wire-up examples: make the skill open context first

Cursor / folder-based skills

Keep skills under your agent’s scanned skills directory, e.g. skills/support-triage/SKILL.md.
Keep one shared context file at a stable path the agent can read, e.g. context.md at the project root (or docs/context.md).
Add an explicit first step inside each skill’s Process section:

## Process
1. Read `context.md` (project root) before drafting. Use Product, Voice, Must-not, and Current offer. If the file is missing, ask for those fields once—do not invent them.
2. …

Reload the agent / start a fresh session so the skill text is indexed.
Trigger with the skill name (“use support-triage on these tickets”) plus the day-of payload—not another ICP essay.

Projects, Custom GPTs, plain chat

No skills folder? Same split, different delivery:

Paste the skill body into project instructions (procedure only).
Attach or paste context.md as project knowledge / a pinned first document.
Day-of messages carry only the task (tickets, PR list, research question).

Order matters: skill defines the job; context supplies today’s truth; the user message supplies the instance. Mixing all three into one mega-prompt is how stale prices sneak into “stable” instructions.

One line that prevents most regressions

Wherever you document the skill for teammates, add: “Edit context.md for product facts. Do not edit SKILL.md for price or tone.” That sentence saves more consistency than another paragraph of process.

Indie SaaS week-1 starter set

You do not need a dozen skills to prove the pattern. For a live product week, install one procedure skill and a thin context file.

Skill: support triage (classify severity, draft a human reply, flag what needs a person). Keep severity levels, reply quality bar, and “never invent a fix timeline” in the skill—those are process.

Context (thin):

# SaaS context
- Product: <name> — <one-liner>
- Plans: Free / Pro $X / Team $Y (confirm before stating)
- Tone: crisp, no guilt, no fake urgency
- Must-not: no refund promises without founder OK; no password-reset links in drafts
- Docs: <url> · Status: <url>
- Known incident this week: <none | one line>

Day-1 exercise (about 30–40 minutes):

Drop five real tickets (or Discord questions) into chat.
Ask the agent to run support-triage after reading context.
Check drafts against Must-not and Current offer—not against whether the prose “sounds AI.”
Fix misses by editing context, then re-run the same skill. Notice you did not rewrite the procedure.

Optional second skill later the same week: changelog draft. Reuse the same context.md. That reuse is the payoff—one fact file, many procedures.

Resist dumping an entire pack on day one. One skill + one context file teaches the split better than twenty overlapping triggers with no shared facts.

Failure modes (and the fix)

Failure	What it looks like	Fix
Stale prices in the skill	Agent quotes last quarter’s Pro plan	Move offer lines to `context.md`; add “confirm before stating”
One mega-skill	200-line file mixing ICP, steps, brand story, and templates	Split: skill = steps + output; context = facts; template = shape
20 skills, no context	Each skill vaguely “knows” the product; voice drifts	One shared context; every skill’s step 1 reads it
Context novel	800-line wiki the model skims	Cap to must-use fields; link out for deep docs
Skills that restate context	Duplicate tone rules in five `SKILL.md` files	Delete duplicates; point to the file
Forgotten path	“Read context.md” but file lives elsewhere	Stable relative path; mention it in SETUP for the repo
Editing the wrong file under pressure	Hotfix → someone patches the skill with a coupon code	Team rule: facts → context only

Most “the agent forgot our brand” complaints are missing or stale context, not a weak model. Most “we’re scared to update the skill” complaints mean facts were trapped inside procedure.

Try the format free

If you want a concrete SKILL.md to practice against—not another abstract diagram—use a research-brief skill as the structural example: clear when-to-use, goal, process, output shape, anti-patterns. Pair it with the context.md template above. Run one real brief for your product and force the skill to read context before writing. That single pass shows whether the split fits your stack.

Try a clean skill layout free

AgentOps Lab free teaser (1 skill + sample prompts + template):
https://moneyprinter-ops.itch.io/ai-agent-ops-free-teaser

Full AI Agent Ops Pack ($19) and Indie SaaS Agent Ops Pack ($24) stay on itch when you want more workflows—no income claims, just files.

Stop Paying the Blank-Chat Tax: Install a SKILL.md in 10 Minutes

AgentOps Lab — Sun, 01 Nov 2026 04:31:01 +0000

Stop Paying the Blank-Chat Tax: Install a SKILL.md in 10 Minutes

A practical install path for Cursor-style agents—plus a free teaser so you can try the format before buying anything.

You open a new agent chat. You type a vague ask. You get a vague answer. You re-prompt. You re-prompt again. Twenty minutes later you have burned tokens and still do not have something you would send a teammate.

That loop is the blank-chat tax. It is not “AI failing.” It is missing job instructions. This post shows how a short SKILL.md cuts that tax, how to install one in about ten minutes, and how to land a first useful win in under 45 minutes.

What the blank-chat tax actually is

A blank chat starts with almost no system context: no role, no process, no definition of done. The model defaults to generic advice. You then pay twice—once in tokens, again in time—while you invent the missing structure through re-prompts.

Typical shape:

You ask for “research on competitors.”
You get a padded overview with soft claims and no sources.
You add “be specific,” “use a table,” “include next steps.”
The third or fourth reply finally looks usable.

The cost is not mysterious. Empty context → generic answers → re-prompt loops. Skills fix the front of that pipeline so you are not rediscovering the same structure every session.

Skills beat mega-prompts

A mega-prompt tries to stuff everything into one wall of text: tone, product facts, process, edge cases. It goes stale the moment your product or audience changes, and it is hard to reuse across tools.

A SKILL.md is smaller and sharper. Treat it as a job description for one kind of work:

When to use — trigger phrases or situations
Goal — what “good” means in one sentence
Steps — 3–5 concrete process steps
Done criteria — what the output must look like before you stop

Keep product facts (company name, audience, tone, constraints, metrics) in a separate context.md. Point the skill at that file. The skill stays stable; the context file changes when the product does. That split is what makes a skill reusable across projects instead of a one-off paste.

Install a SKILL.md (Cursor / agent folders)

This path matches how Cursor-style agents and similar skill folders work. Adjust folder names to whatever your agent actually scans.

Unpack the skill zip (or clone the folder) somewhere you control.
Copy one skill folder — for example skills/research-brief/ containing SKILL.md — into the directory your agent discovers skills from (project skills folder, managed-skills path, or your bot’s skill store).
Reload the agent / restart the session so new SKILL.md files are indexed.
Trigger by name — ask with the skill’s name or its documented trigger phrase (“write a research brief on…”).

Rule: start with 1–3 skills only. Loading a dozen at once dilutes routing; the agent may ignore half of them or pick the wrong one. Add more only after the first ones fire reliably.

If nothing changes after install, check the scanned path first. A skill that sits outside the agent’s discovery tree is invisible no matter how good the file is.

Paste path for Projects / Custom GPTs / plain chat

Not every host has a skills directory. The same structure still works:

Open SKILL.md and paste the body into project instructions, custom GPT instructions, or as the first message in a plain chat.
Optionally attach the matching template as project knowledge.
Then paste today’s task prompt (topic, sources, deadline).

You are not changing the skill design—only the delivery mechanism. Skill first, day-of prompt second. That order keeps the process stable while the topic changes.

For ChatGPT or any one-off chat: paste skill → paste prompt → ask the model to fill the template. Same three pieces as a folder-based install.

First win in under 45 minutes

Use a research-brief skill as the dry run. You need three files (or the free teaser that bundles them):

SKILL.md for research briefs
One sample prompt (topic + sources + audience)
A research-brief template

Rough timeline:

Minutes	Action
2	Write the decision question in one sentence
5	List 5–10 sources (pages, docs, notes)
15	Ask the agent to fill the template using the skill
10	Verify every number and claim; mark Unknowns
10	Add three next actions you will actually do

Done looks like: a one-page brief a teammate could act on without asking for your raw notes—bottom line up front, evidence tagged Fact / Inference / Unknown, and ranked next actions. If you would not send it in Slack, it is not done yet.

That single pass teaches the format better than reading ten more prompt dumps.

Common failure modes

Symptom	Likely cause	Fix
Agent ignores the skill	File not on a scanned path	Move the folder; reload
Still generic output	No project facts	Add `context.md` (audience, tone, constraints) and reference it
Wrong skill fires	Too many skills, overlapping triggers	Keep 1–3 active; rename conflicting triggers
Instructions feel ignored	Mega-prompt mixed into the skill	Strip facts out of `SKILL.md`; keep steps only
Great once, stale next week	Product details baked into the skill	Fork context, not the whole skill

Most “skills don’t work” reports are install or routing problems, not model problems. Fix path and cardinality before rewriting the skill.

What to do next (soft upsell, no income claims)

If you want files instead of starting from a blank SKILL.md, grab the free teaser: 1 research-brief skill, sample prompts, and a template. Run one real brief on a topic you care about. That is enough to decide whether the layout fits your stack.

If you outgrow the single skill and want the rest of the library—more skills, workflows, and templates—the full AI Agent Ops Pack (and the Indie SaaS vertical pack) sit on the same itch page family. Try the free slice first; buy only if the format already helped.

Try the format free

Download the free AI Agent Ops teaser (1 skill + sample prompts + template) from AgentOps Lab:

https://moneyprinter-ops.itch.io/ai-agent-ops-free-teaser

If the layout helps, the full AI Agent Ops Pack and Indie SaaS Agent Ops Pack are on the same itch page family—no income promises, just files you can run.

Shipped: AI Agent Ops Pack v1 on itch.io ($19)

AgentOps Lab — Sat, 31 Oct 2026 17:11:29 +0000

I kept rebuilding the same agent prompts for research briefs, weekly status, competitor teardowns, and ship checklists.

So I packaged them as markdown skills + workflows (Cursor / Grok Bot / any agent that can follow a skill file):

10 skills (SKILL.md style)
40+ prompts by job
6 multi-step workflows
4 templates

Not a video course. Not an “AI side hustle.” Download → open → run.

Free teaser: https://moneyprinter-ops.itch.io/ai-agent-ops-free-teaser

Full pack ($19): https://moneyprinter-ops.itch.io/ai-agent-ops-pack

Optional Indie SaaS vertical ($24): https://moneyprinter-ops.itch.io/indie-saas-agent-ops-pack

No income promises — just reusable agent ops files. Feedback on listing clarity welcome.

DEV Community: AgentOps Lab

context.md vs SKILL.md: Stop Pasting Product Facts Into Every Prompt

The symptom: the same product paragraph every time

Two files, two jobs

What belongs in the skill (and what doesn’t)

Minimal context.md template

Wire-up examples: make the skill open context first

Cursor / folder-based skills

Projects, Custom GPTs, plain chat

One line that prevents most regressions

Indie SaaS week-1 starter set

Failure modes (and the fix)

Try the format free

Try a clean skill layout free

Stop Paying the Blank-Chat Tax: Install a SKILL.md in 10 Minutes

Stop Paying the Blank-Chat Tax: Install a SKILL.md in 10 Minutes

What the blank-chat tax actually is

Skills beat mega-prompts

Install a SKILL.md (Cursor / agent folders)

Paste path for Projects / Custom GPTs / plain chat

First win in under 45 minutes

Common failure modes

What to do next (soft upsell, no income claims)

Try the format free

Shipped: AI Agent Ops Pack v1 on itch.io ($19)

Minimal `context.md` template