Add blog post on writing agent skills for datafusion-python by timsaucer · Pull Request #187 · apache/datafusion-site

timsaucer · 2026-05-22T16:26:31Z

Staged site: https://datafusion.staged.apache.org/blog/2026/05/22/writing-agent-skills/

Walks through the user-facing vs developer skill split, the TPC-H grounding exercise, and the iterative feedback loop we used to keep the skills honest as the API moved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ntjohnson1

All nits so accept or reject however makes sense to you. This looks great. Excited for when this publishes

ntjohnson1 · 2026-05-23T13:33:45Z

+
+[TOC]
+
+If you maintain an open source project, a growing fraction of the people


Suggested change

If you maintain an open source project, a growing fraction of the people

If you maintain an open source project, a growing fraction of people

ntjohnson1 · 2026-05-23T13:33:56Z

+[TOC]
+
+If you maintain an open source project, a growing fraction of the people
+using your library are not typing code directly anymore — they are asking an


Suggested change

using your library are not typing code directly anymore — they are asking an

using your library are not typing code anymore — they are asking an

ntjohnson1 · 2026-05-23T13:36:11Z

+Concretely, you will get out of this post:
+
+- A pattern for splitting skills by audience — user-facing vs.
+  contributor-facing — and why the split matters more than it sounds.


Suggested change

contributor-facing — and why the split matters more than it sounds.

contributor-facing — and why the split matters.

ntjohnson1 · 2026-05-23T13:36:28Z

+- A pattern for splitting skills by audience — user-facing vs.
+  contributor-facing — and why the split matters more than it sounds.
+- A workflow for keeping skills in sync with a moving API by treating the
+  skill itself as the maintenance tool.


Suggested change

skill itself as the maintenance tool.

skill itself as a maintenance tool.

ntjohnson1 · 2026-05-23T13:40:20Z

+to generate code. That distinction matters: a good user guide is patient and
+walks the reader through concepts; a good skill is opinionated and tells the
+model the exact pattern to emit.
+


Suggested change

[Skill]: https://agentskills.io/home

ntjohnson1 · 2026-05-23T15:05:11Z

+is silent on something it should cover. Codify the reasoning, don't
+rely on the agent finding it again next time.
+
+The next two sections describe two different things we did after the


Two twos felt redundant

Suggested change

The next two sections describe two different things we did after the

The next two sections describe different things we did after the

ntjohnson1 · 2026-05-23T15:05:46Z

+
+A draft skill needs to be tested against something more demanding than the
+ad-hoc prompts the author used while writing it. We needed a way to confirm
+that the skill, once handed to a fresh agent, actually produced code that


Suggested change

that the skill, once handed to a fresh agent, actually produced code that

that the skill, once handed to a fresh agent, actually produces code that

There are mixed tenses between past work then current validation. I think this aligns them consistently

ntjohnson1 · 2026-05-23T15:06:23Z

+A draft skill needs to be tested against something more demanding than the
+ad-hoc prompts the author used while writing it. We needed a way to confirm
+that the skill, once handed to a fresh agent, actually produced code that
+*ran* and returned *correct answers* on real workloads — not just on the


Suggested change

*ran* and returned *correct answers* on real workloads — not just on the

*runs* and returns *correct answers* on real workloads — not just on the

ntjohnson1 · 2026-05-23T15:12:17Z

+person would follow, it is a candidate for a skill — and the act of
+writing the skill forces you to make the checklist explicit.
+
+The three correspond to the three places maintenance drift shows up in a


Suggested change

The three correspond to the three places maintenance drift shows up in a

The skills correspond to the three places maintenance drift shows up in a

ntjohnson1 · 2026-05-23T15:13:01Z

+The three correspond to the three places maintenance drift shows up in a
+binding project like ours:
+
+- **`check-upstream`** — *the public API of the wrapped library moved


wrapped library felt ambiguous if we were talking about the library that does the wrapping or the source

Suggested change

- **`check-upstream`** — *the public API of the wrapped library moved

- **`check-upstream`** — *the public API of the source library moved

andygrove · 2026-05-25T03:28:19Z

The staged URL is not working for me

kevinjqliu · 2026-05-25T04:38:13Z

perhaps the staging was overwritten by the ballista 53 blog, https://datafusion.staged.apache.org/blog/

ntjohnson1 approved these changes May 23, 2026

View reviewed changes


		[TOC]

		If you maintain an open source project, a growing fraction of the people

	using your library are not typing code directly anymore — they are asking an
	using your library are not typing code anymore — they are asking an

	contributor-facing — and why the split matters more than it sounds.
	contributor-facing — and why the split matters.

	skill itself as the maintenance tool.
	skill itself as a maintenance tool.

	The next two sections describe two different things we did after the
	The next two sections describe different things we did after the

	that the skill, once handed to a fresh agent, actually produced code that
	that the skill, once handed to a fresh agent, actually produces code that

	ran and returned correct answers on real workloads — not just on the
	runs and returns correct answers on real workloads — not just on the

	The three correspond to the three places maintenance drift shows up in a
	The skills correspond to the three places maintenance drift shows up in a

	- `check-upstream` — *the public API of the wrapped library moved
	- `check-upstream` — *the public API of the source library moved

Conversation

timsaucer commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ntjohnson1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andygrove commented May 25, 2026

Uh oh!

kevinjqliu commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

timsaucer commented May 22, 2026 •

edited

Loading