Skip to main content

Smart Prompting, Stronger AI Agent Outcomes — What Actually Works

· 6 min read

Over the past few months, one prompting pattern has consistently produced better AI agents for me.

Not bigger prompts.

Not more skills.

Just a better separation of responsibilities.

The Framework​

My current approach boils down to three pillars:

✅ Lean Prompts​

Tell the agent what to do, not how to do everything.

  • Be clear about the goal
  • Include only what's essential
  • Avoid fluff and unnecessary details

Instead of writing a 500-line prompt that tries to cover every edge case, I keep it short:

"List the top 5 features of our product."

That's it. No preamble. No over-explanation. The agent doesn't need a backstory.

📚 Rich Artifacts & Context​

Put the heavy lifting into documentation, examples, schemas, and project knowledge — not the prompt itself.

  • Add docs, schemas, references
  • Share examples and constraints
  • Include relevant project knowledge

This is where files like architecture.md, schema.json, coding-standards.md, and examples/ come in. The agent reads these as context, so your prompt stays lean while the agent still has everything it needs.

🧩 Small, Focused Skills​

Keep skills modular with a single responsibility instead of building giant "do everything" tools.

  • Single purpose
  • Modular and composable
  • Easy to maintain and extend

Think query-data, run-tests, generate-report, create-pr — each skill does one thing well. Not a monolithic "handle-everything" skill that tries to be clever.

Why This Works​

The result of applying this pattern consistently:

  • More consistent outputs — The agent isn't distracted by irrelevant instructions
  • Better reasoning — Smaller context means the agent focuses on what matters
  • Easier maintenance — Change one skill without breaking everything else
  • Lower token usage — Less prompt bloat means faster, cheaper responses

What I Learned Building This in Practice​

This isn't theoretical. I arrived at this framework through months of hands-on work building AI agent skills and tools. Here are some concrete examples from my own experience:

Building the Cosmos DB Best Practices Skill​

When I started building skills for the Azure Cosmos DB Agent Kit, I fell into the "more is better" trap. We wrote down everything — partition key strategies, indexing decisions, query optimization, change feed patterns, vector search setup. The skill file kept growing past 2,000 lines.

Then we started measuring. Some of that guidance made zero measurable difference — the model already knew it from training data. A few cases actually made things worse because the model spent attention budget processing our instructions instead of solving the problem.

The fix? We trimmed to a ~400-line core backed by reference files that load on-demand. Performance improved. Token usage dropped by ~60%. The lesson: skills matter most where the model's training data is thin.

I wrote about this journey in depth in my post What Six Months of Building AI Agent Skills Taught Me About Writing for Machines.

Using Skills for Real Customer Scenarios​

The framework proved itself in real support scenarios. When a customer needed help understanding why they couldn't scale down their Cosmos DB autoscale throughput after a test, I used the best practices skill to quickly generate accurate, context-aware guidance. The skill provided the precise domain knowledge the agent needed — not a generic explanation, but the exact autoscale behavior rules. Lean prompt + rich context = accurate answer in seconds.

Extending Skills for Customer-Specific Scenarios​

Enterprise customers like Walmart and Nike started asking for customized skills tailored to their specific use cases. This validated the modular approach — because each skill had a single responsibility, we could extend or compose them for customer scenarios without rewriting the core. A monolithic skill would have made this nearly impossible.

Skill Descriptions Are Underrated​

One of the subtler lessons: how you describe a skill matters as much as what's in it. Our first skill description was vague — "Best practices for Cosmos DB." It got triggered for everything remotely related, including completely wrong contexts.

The fix was adding explicit scope boundaries and negative triggers. A good description says what the skill is for and what it's not for. "Do NOT use for MongoDB, PostgreSQL, or DynamoDB" is surprisingly effective at preventing false matches. We also found that skill registries degrade in selection accuracy past ~20-30 entries without a retrieval filter.

The Anti-Pattern: Why Long Prompts Fail​

I've seen (and written) the opposite approach — massive prompts that try to anticipate every scenario. They fail for predictable reasons:

  1. Context rot — Even models with 200K token windows lose attention in the middle. Research confirms this. A big context window is not the same as a big useful context window.

  2. Diminishing returns — Past ~800 lines, performance degrades regardless of model. More tokens ≠ better output.

  3. Maintenance nightmare — One giant prompt means every change risks breaking something else. Small skills are independently testable and updatable.

  4. Duplicating training data — Frontier models already know common patterns. Writing skills for things models already handle is wasted effort.

How to Get Started​

If you want to try this framework:

  1. Audit your prompts — Find the ones that are doing too much. Split the "what to do" from the "how to do it."

  2. Extract context into files — Move schemas, examples, coding standards, and domain knowledge into separate artifacts the agent can reference.

  3. Build small skills — One skill per capability. If a skill description needs the word "and," it's probably two skills.

  4. Measure — Even a crude evaluation (5 test cases, 3 trials each) is infinitely better than vibes. You'll be surprised what the model already knows.

  5. Iterate — Treat skills like code. Test them. Version them. Cut what doesn't help.

What's Your Prompting Philosophy?​

I'm curious if others have arrived at the same conclusion.

  • Do you rely on long prompts?
  • Do you invest more in context?
  • Or have you found another approach that works even better?

Share your tips, prompts, or real-world examples — let's learn from each other.