context.md 與 SKILL.md 如何分工，避免每次提示詞重貼產品資料

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:

1. Monday — draft a support reply → paste ICP, plan names, tone rules.
2. Tuesday — changelog → paste the same block plus “don’t promise dates.”
3. Wednesday — competitor note → paste again, then add this week’s price.
4. 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.

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

1. Keep skills under your agent’s scanned skills directory, e.g. skills/support-triage/SKILL.md.
2. 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).
3. 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. …

1. Reload the agent / start a fresh session so the skill text is indexed.
2. 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:

1. Paste the skill body into project instructions (procedure only).
2. Attach or paste context.md as project knowledge / a pinned first document.
3. 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):

1. Drop five real tickets (or Discord questions) into chat.
2. Ask the agent to run support-triage after reading context.
3. Check drafts against Must-not and Current offer—not against whether the prose “sounds AI.”
4. 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)

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.