This is an automated email from the ASF dual-hosted git repository.
wenjin272 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new 75485347 [docs] Document coding-agent Skill usage and refresh homepage
navigation (#1273)
75485347 is described below
commit 7548534712ce5f63984debd5b71e03c80905f450
Author: Wenjin Xie <[email protected]>
AuthorDate: Sat Oct 17 20:52:26 2026 +0800
[docs] Document coding-agent Skill usage and refresh homepage navigation
(#1273)
Generated-by: Codex 26.1013.31256 (GPT-6)
Co-authored-by: Codex <[email protected]>
---
docs/assets/_custom.scss | 17 +++
docs/content/_index.md | 22 ++--
.../content/docs/development/coding-agent-skill.md | 132 +++++++++++++++++++++
docs/content/docs/get-started/overview.md | 3 +-
docs/layouts/_default/baseof.html | 2 +-
docs/layouts/shortcodes/branch.html | 21 ++++
6 files changed, 187 insertions(+), 10 deletions(-)
diff --git a/docs/assets/_custom.scss b/docs/assets/_custom.scss
index 72e49b74..53ac63b7 100644
--- a/docs/assets/_custom.scss
+++ b/docs/assets/_custom.scss
@@ -241,3 +241,20 @@ pre.chroma code {
.table-inline {
background: white;
}
+
+.docs-home .book-columns > div:last-child {
+ display: flex;
+ flex-direction: column;
+}
+
+.docs-home-meta {
+ margin-top: auto;
+ padding-top: 1rem;
+ border-top: 1px solid var(--gray-200);
+ font-size: 0.875rem;
+ color: #666;
+
+ p {
+ margin: 0 0 0.5rem;
+ }
+}
diff --git a/docs/content/_index.md b/docs/content/_index.md
index eeb5dbcb..06d23997 100644
--- a/docs/content/_index.md
+++ b/docs/content/_index.md
@@ -36,11 +36,16 @@ It provides a step by step introduction on how to install
Flink Agents and build
- [Use the Built-in ReAct Agent]({{< ref
"docs/get-started/quickstart/react_agent" >}})
- [Define an Agent with YAML]({{< ref "docs/get-started/quickstart/yaml_agent"
>}})
-### Build and Operate
+### How to Build an Agent
-* [Calling LLMs]({{< ref "docs/development/calling-llms" >}}), [Tool Use]({{<
ref "docs/development/calling-llms/tool_use" >}}) and [Memory]({{< ref
"docs/development/memory/overview" >}}) - The building blocks of an agent
-* [Integrate with Flink]({{< ref "docs/development/integrate_with_flink" >}})
- Run an agent inside a Flink job
-* [Deployment]({{< ref "docs/operations/deployment" >}}) and [Monitoring]({{<
ref "docs/operations/monitoring" >}}) - Take an agent to production
+* [Create an Agent]({{< ref "docs/development/create-agent" >}}) and [Built-in
ReAct Agent]({{< ref "docs/development/react_agent" >}}) - Define an agent or
use the built-in ReAct agent
+* [Calling LLMs]({{< ref "docs/development/calling-llms" >}}) - Work with
models, prompts, tools, MCP, and runtime Skills
+* [Memory]({{< ref "docs/development/memory" >}}) and [Vector Search]({{< ref
"docs/development/vector-search" >}}) - Manage context and retrieve relevant
information
+* [Multi-Agent]({{< ref "docs/development/multi-agent" >}}) and [Integrate
with Flink]({{< ref "docs/development/integrate_with_flink" >}}) - Compose
agents and connect them to Flink jobs
+
+### How to Operate an Agent
+
+* [Deployment]({{< ref "docs/operations/deployment" >}}), [Configuration]({{<
ref "docs/operations/configuration" >}}), and [Monitoring]({{< ref
"docs/operations/monitoring" >}}) - Deploy, configure, and monitor agents
<--->
@@ -58,8 +63,9 @@ See the [Apache Flink
website](https://flink.apache.org/what-is-flink/community/
There is a weekly online sync. Everyone is welcome to join. Please find the
schedule, agenda for the next sync, and records of previous syncs in this
[github discussion
page](https://github.com/apache/flink-agents/discussions/419).
-{{< /columns >}}
-
-Flink Agents is developed under the umbrella of [Apache
Flink](https://flink.apache.org/).
-
+<footer class="docs-home-meta">
+<p>Flink Agents is developed under the umbrella of <a
href="https://flink.apache.org/";>Apache Flink</a>.</p>
{{< build_time >}}
+</footer>
+
+{{< /columns >}}
diff --git a/docs/content/docs/development/coding-agent-skill.md
b/docs/content/docs/development/coding-agent-skill.md
new file mode 100644
index 00000000..9657d01e
--- /dev/null
+++ b/docs/content/docs/development/coding-agent-skill.md
@@ -0,0 +1,132 @@
+---
+title: "Build with a Coding Agent"
+weight: 8
+type: docs
+---
+<!--
+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.
+-->
+
+# Build with a Coding Agent
+
+The **flink-agents-dev** Skill gives your coding agent Flink Agents-specific
+instructions, reference material, and YAML schemas. Use it to scaffold an
+application, modify an existing Agent, or investigate and validate application
code.
+It covers Java, Python, and YAML authoring, subject to the APIs supported by
your
+target Flink Agents version.
+
+Install it in your coding agent's environment. It is an optional development
+aid; installing it does not install Flink Agents or add a dependency to your
Flink
+job. For Skills that an Agent loads while running, see
+[Runtime Skills]({{< ref "docs/development/calling-llms/skills" >}}).
+
+## Install the Skill
+
+Run the following command and follow the prompts to select your coding agent:
+
+```bash
+npx skills add 'apache/flink-agents#{{< branch >}}@flink-agents-dev'
+```
+
+This installs the
+[flink-agents-dev Skill](https://github.com/apache/flink-agents/tree/{{<
branch >}}/dev/agent-skills/flink-agents-dev)
+from the `{{< branch >}}` branch, matching this documentation. Use the
documentation
+for your target Flink Agents version to install the corresponding Skill. Skill
+updates can be made on that branch without waiting for a new Flink Agents
release.
+
+After installation, explicitly ask your coding agent to use `flink-agents-dev`
+when working on a Flink Agents application.
+
+## Use the Skill
+
+Describe your task and provide any choices you have already made: the Flink
Agents
+and Flink versions, Agent-definition API, application language, and
integrations.
+For an existing application, let the coding agent inspect its dependencies and
code.
+The Skill guides the coding agent to resolve missing framework choices before
+generating the corresponding files.
+
+When scaffolding a new application, the Skill guides the coding agent to
generate:
+
+- Project structure and dependency files for the selected versions and
language.
+- Agent definitions, Resource declarations, and Action/Event wiring supported
by
+ built-in behavior or requirements you have supplied.
+- Custom Action and Tool signatures, a Flink job entry point, and validation
commands
+ with a report of the checks performed.
+
+By default, business behavior that you have not specified remains a scaffold.
This
+includes custom Action and Tool bodies, data transformations, prompts, external
+service calls, and runtime Skill instructions. Required model settings,
endpoints,
+and credentials are marked for configuration when their values are unknown. The
+Skill does not invent these details from a high-level application idea.
Unimplemented
+functions contain focused TODOs and fail explicitly when invoked.
+
+For example, to start a project:
+
+```text
+Use the flink-agents-dev Skill to scaffold a Flink Agents application.
+Help me choose compatible Flink Agents and Flink versions and an Agent API.
+I want an Agent that classifies incoming support requests.
+Include the project dependencies, a Flink job entry point, and validation
steps.
+```
+
+You can fill in the remaining parts yourself or ask the coding agent to
implement
+them in a follow-up. Provide the business rules, expected inputs and outputs,
+service API contracts, and error behavior needed for that implementation. For
example:
+
+```text
+Continue implementing the scaffold using the classification rules and
input/output
+examples in the attached specification. Implement the custom Actions and Tools,
+and add tests for the specified behavior. Ask me about any missing requirements
+before implementing behavior that the specification does not define.
+```
+
+For an existing project:
+
+```text
+Use the flink-agents-dev Skill to review this application's Agent definition
+and custom Actions. Keep the versions in the project dependencies.
+Check API usage, Resource references, and Event/Action connections.
+Run the available checks and distinguish confirmed failures from checks
+that need external services.
+```
+
+The Skill's source branch does not change your application's dependency
versions.
+Tell the coding agent which version the application targets. YAML validation
requires
+a schema for that target version; a development schema is not a substitute for
a
+missing release schema.
+
+## Check the result
+
+Review the generated files and the coding agent's validation report before
running the
+application. Check that:
+
+- Dependencies and API calls match the target Flink Agents and Flink versions.
+- Required configuration and unfinished business logic are clearly identified.
+- YAML validation, imports or compilation, tests, and actual job execution are
+ reported separately. Passing schema validation alone does not establish that
an
+ application runs.
+- Checks requiring models or other external services are marked as untested
when
+ those services were unavailable.
+
+Use [Setup]({{< ref "docs/get-started/setup" >}}) for environment requirements,
+[Choose APIs and Languages]({{< ref
"docs/development/create-agent/choose-apis-and-languages" >}})
+for API and language choices, and
+[Create an Agent]({{< ref "docs/development/create-agent/overview" >}})
+for the concepts behind generated code. For YAML applications, use the
+[YAML API reference]({{< ref "docs/development/create-agent/yaml" >}}); for
job wiring,
+see [Integrate with Flink]({{< ref "docs/development/integrate_with_flink"
>}}).
diff --git a/docs/content/docs/get-started/overview.md
b/docs/content/docs/get-started/overview.md
index 4b52aa5c..9738af16 100644
--- a/docs/content/docs/get-started/overview.md
+++ b/docs/content/docs/get-started/overview.md
@@ -54,7 +54,8 @@ Start with [Setup]({{< ref "docs/get-started/setup" >}}),
then choose a Quicksta
- [Use the Built-in ReAct Agent]({{< ref
"docs/get-started/quickstart/react_agent" >}})
- [Define an Agent with YAML]({{< ref "docs/get-started/quickstart/yaml_agent"
>}})
-For an optional authoring aid, see the [Coding-agent
Skill](https://github.com/apache/flink-agents/tree/main/dev/agent-skills/flink-agents-dev).
+To build Flink Agents applications with a coding agent, see
+[Build with a Coding Agent]({{< ref "docs/development/coding-agent-skill" >}}).
## Preview Status
diff --git a/docs/layouts/_default/baseof.html
b/docs/layouts/_default/baseof.html
index f9b76002..e0928b7e 100644
--- a/docs/layouts/_default/baseof.html
+++ b/docs/layouts/_default/baseof.html
@@ -115,7 +115,7 @@ under the License.
{{ end }}
{{ define "main" }}
- <article class="markdown">
+ <article class="markdown{{ if .IsHome }} docs-home{{ end }}">
{{- .Content -}}
</article>
{{ end }}
diff --git a/docs/layouts/shortcodes/branch.html
b/docs/layouts/shortcodes/branch.html
new file mode 100644
index 00000000..f4b80cd0
--- /dev/null
+++ b/docs/layouts/shortcodes/branch.html
@@ -0,0 +1,21 @@
+{{/*
+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.
+*/}}{{/*
+ Interpolates the source branch matching this documentation.
+ Parameters: None
+*/}}{{- $.Site.Params.Branch -}}
