docs: replace raw SKILL.md include with a human-written AI-assistants page

The previous approach embedded the repo-root `SKILL.md` on the docs
site via a myst `{include}`. That file is written for agents -- dense,
skill-formatted, and not suited to a human browsing the User Guide. It
also relied on a fragile `:start-line:` offset to strip YAML
frontmatter.

Replace it with `docs/source/ai-coding-assistants.md`, a short
human-readable page that mirrors the README section added in #1503:
what the skill is, how to install it via `npx skills` or a manual
pointer, and what kinds of things it covers. `SKILL.md` stays at the
repo root as the single source of truth; agents fetch the raw GitHub
URL directly.

`llms.txt` is updated to point its Agent Guide entry at
`raw.githubusercontent.com/.../SKILL.md` and to include the new
human-readable page as a secondary link. The User Guide toctree now
references `ai-coding-assistants` in place of the removed `skill`
stub.

Verified with `sphinx-build -W --keep-going` against the full docs
tree.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: timsaucer

docs/source/ai-coding-assistants.md

@@ -0,0 +1,82 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Using DataFusion with AI Coding Assistants
+
+If you write DataFusion Python code with an AI coding assistant — Claude
+Code, Cursor, Windsurf, Cline, Codex, Copilot, Gemini CLI, or any other
+agent that supports skill discovery — this project ships machine-readable
+guidance so the assistant produces idiomatic code rather than guessing from
+its training data.
+
+## What is published
+
+- **[`SKILL.md`](https://github.com/apache/datafusion-python/blob/main/SKILL.md)** —
+  a dense, skill-oriented reference covering imports, data loading,
+  DataFrame operations, expression building, SQL-to-DataFrame mappings,
+  idiomatic patterns, and common pitfalls. Follows the
+  [Agent Skills](https://agentskills.io) open standard.
+- **[`llms.txt`](llms.txt)** — an entry point for LLM-based tools
+  following the [llmstxt.org](https://llmstxt.org) convention. Categorized
+  links to the skill, user guide, API reference, and examples.
+
+Both files live at stable URLs so an agent can discover them without a
+checkout of the repo.
+
+## Installing the skill
+
+**Preferred:** run
+
+```shell
+npx skills add apache/datafusion-python
+```
+
+This installs the skill in any supported agent on your machine (Claude
+Code, Cursor, Windsurf, Cline, Codex, Copilot, Gemini CLI, and others).
+The command writes the pointer into the agent's configuration so that any
+project you open that uses DataFusion Python picks up the skill
+automatically.
+
+**Manual:** if you are not using the `skills` registry, paste this single
+line into your project's `AGENTS.md` or `CLAUDE.md`:
+
+```
+For DataFusion Python code, see https://github.com/apache/datafusion-python/blob/main/SKILL.md
+```
+
+Most assistants resolve that pointer the first time they see a
+DataFusion-related prompt in the project.
+
+## What the skill covers
+
+Writing DataFusion Python code has a handful of conventions that are easy
+for a model to miss — bitwise `&` / `|` / `~` instead of Python
+`and` / `or` / `not`, the lazy-DataFrame immutability model, how window
+functions replace SQL correlated subqueries, the `case` / `when` builder
+syntax, and the `in_list` / `array_position` options for membership
+tests. The skill enumerates each of these with short, copyable examples.
+
+It is *not* a replacement for this user guide. Think of it as a distilled
+reference the assistant keeps open while it writes code for you.
+
+## If you are an agent author
+
+The skill file and `llms.txt` are the two supported integration points.
+Both are versioned along with the release and follow open standards — no
+project-specific handshake is required.

docs/source/index.rst

@@ -78,7 +78,7 @@ Example
    user-guide/configuration
    user-guide/sql
    user-guide/upgrade-guides
-   skill
+   ai-coding-assistants
 
 
 .. _toc.contributor_guide:

docs/source/llms.txt

@@ -4,7 +4,8 @@
 
 ## Agent Guide
 
-- [SKILL.md (agent skill)](https://datafusion.apache.org/python/skill.html): idiomatic DataFrame API patterns, SQL-to-DataFrame mappings, common pitfalls, and the full `functions` catalog. Primary source of truth for writing datafusion-python code.
+- [SKILL.md (agent skill, raw)](https://raw.githubusercontent.com/apache/datafusion-python/main/SKILL.md): idiomatic DataFrame API patterns, SQL-to-DataFrame mappings, common pitfalls, and the full `functions` catalog. Primary source of truth for writing datafusion-python code.
+- [Using DataFusion with AI coding assistants](https://datafusion.apache.org/python/ai-coding-assistants.html): human-readable guide for installing the skill and manual setup pointers.
 
 ## User Guide