[api][integration] Support agent skills in python by wenjin272 · Pull Request #596 · apache/flink-agents

wenjin272 · 2026-03-26T13:20:58Z

Linked issue: #590

Purpose of change

This PR provides basic support for using agent skills in the Flink Agents Python API. We will further enhance usability in subsequent PRs.

Tests

ut & e2e

API

Yes, add abstraction for agnet skill, and modify the chat model api.

Documentation

doc-needed
doc-not-needed
doc-included

wenjin272 · 2026-03-26T13:25:34Z

Regarding the skill e2e testing, I evaluated qwen3:8b, qwen3.5:4b, and qwen3.5:9b. I found that only qwen3.5:9b with thinking enabled could consistently follow the prompts. However, in the GitHub CI environment, the lack of GPU resources results in very slow model inference, causing tests to take over 30 minutes to complete. Consequently, I have temporarily skipped the skill e2e tests.

I plan to dedicate time later to investigate and resolve this issue.

…eAct agent.

alnzng

Left a few comments, will continue the review. BTW, for future PRs, I'd suggest separating code formatting / refactoring changes from actual logic changes into separate PRs.

alnzng · 2026-04-13T05:12:40Z

+)
+
+
+# TODO: Implement


I would suggest to remove this unimplemented class to avoid confusion.

alnzng · 2026-04-13T05:53:57Z

+
+    @staticmethod
+    def _split_commands(command: str) -> List[str]:
+        """Split a command string by shell operators, respecting quotes.


IIUC, The intention of this method is to extract individual executable commands from a compound command string, not to perform a full shell/bash tokenization. Shell has many operators (e.g. redirection >, >>, <), but this method only targets command-separating operators, those that connect multiple executables. Can you confirm? If yes, let's make it clear in the comment.

Also can we confirm all command-separating operators are covered? For example, are && and || handled correctly?

Out of curiosity, is there any native Python lib or thirdparty lib could provide this kind of functionality? I am not sure if we covered all the necessary shell / bash operators, so I'm thinking if there is a such kind of lib then we could just use it.

Yes, the functionality of this function is indeed as you described.

I could not find an existing third-party library that provides this functionality, so I implemented one myself by referencing agentscope-java.

I added some tests to confirm that delimiters such as &&, |, and ; are handled correctly. Additional tests are needed for ||.

Actually, I currently feel that the security validation for our execute_shell_command might be implemented too simply. I mainly referenced agentscope-java, but the bash tool in Claude Code's implementation includes extensive security validation rules. Therefore, I may refactor it by referencing Claude Code.

alnzng · 2026-04-13T05:55:03Z

+
+            if skill.name != skill_dir.name:
+                logger.warning(
+                    f"The skill name {skill.name}is different from the base directory {skill_dir.name}."


{skill.name}is -> {skill.name} is

alnzng · 2026-04-13T06:10:21Z

+    )
+
+    # Pattern to match key: value format
+    KEY_VALUE_PATTERN = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$")


Looks like we can remove this? I didn't see it is used in any other place.

Initially, the coding agent generated code that used regular expressions to parse YAML frontmatter. I later switched to using a YAML library but forgot to remove these two PATTERNs.
I will remove this.

alnzng · 2026-04-13T06:11:21Z

+            return ParsedMarkdown(metadata={}, content=markdown_content)
+
+        try:
+            metadata = yaml.safe_load(yaml_content)


does markdown frontmatter always follow YAML syntax?

According to the Agent Skills specification: https://agentskills.io/specification#skill-md-format, The SKILL.md file must contain YAML frontmatter followed by Markdown content.

alnzng · 2026-04-13T06:13:08Z

+class MarkdownSkillParser:
+    """Utility for parsing Markdown files with YAML frontmatter."""
+
+    # Pattern to match frontmatter: starts with ---, ends with ---


is below a valid frontmatter?

--- name: tricky description: | This has a --- inside ---

This is a valid frontmatter, and the parsed result is {'description': 'This has a', 'name': 'tricky'}, the left content will be regarded as markdown content inside\n---\n.

alnzng · 2026-04-13T06:15:27Z

+    and optional resource files:
+
+    baseDir/
+    ├── skill-name-1/


What will happen if the users define folder with other different names? For example, this Claude official skill: https://github.com/anthropics/skills/tree/main/skills/skill-creator

I don't quite understand this question. Regarding skill-creator, then the baseDir can be any dir the flink-agents job can access, like /flink/usrlib/skills, and the skill-name-1 will be skill-creator.

xintongsong · 2026-04-14T08:02:38Z

    return func

+
+def skills(func: Callable) -> Callable:


wrong commit

xintongsong · 2026-04-14T08:03:08Z

    "so we will not fix this issue for now."
 )
-def test_long_term_memory_async_execution_in_action(tmp_path: Path) -> None:  # noqa: D103
+def test_long_term_memory_async_execution_in_action(tmp_path: Path) -> None:


wrong commit

xintongsong · 2026-04-14T08:18:58Z

+            Only the first token of a command is checked against this list.
+    """
+
+    paths: List[str] = Field(default_factory=list)


I'd suggest to provide some factory methods, like Skills.from_local_dir() or Skills.from_url(). This aligns with Prompt.from_text() / from_messages(), and is more easy-to-use.

And maybe hide the implementation of Skills from the users.

xintongsong · 2026-04-14T08:40:24Z

        """Get another resource declared in the same Agent."""
+
+    @abstractmethod
+    def generate_skill_discovery_prompt(self, *skill_names: str) -> str:


I'd suggest the name generate_available_skills_prompt

xintongsong · 2026-04-14T08:42:09Z

    VECTOR_STORE = "vector_store"
    PROMPT = "prompt"
    MCP_SERVER = "mcp_server"
+    SKILL = "skill"


xintongsong · 2026-04-14T08:42:17Z

    TOOL("tool"),
-    MCP_SERVER("mcp_server");
+    MCP_SERVER("mcp_server"),
+    SKILL("skill");


xintongsong · 2026-04-14T09:09:29Z

+from flink_agents.runtime.skill.skill_repository import SkillRepository
+
+
+class RegisteredSkill:


Why do we need both AgentSkill and RegisteredSkill ?

xintongsong · 2026-04-14T09:15:11Z

+    allowed_script_types: List[str] = Field(
+        default_factory=lambda: ["shell", "python"]
+    )
+    allowed_commands: List[str] = Field(default_factory=list)


This doesn't sounds right. How is allowed script types / commands an attribute of the skills? If the model decide to execute something, how do we know it's following the instructions of a skill or not?

xintongsong · 2026-04-14T09:22:35Z

+class ExecuteCommandArgs(BaseModel):
+    """Arguments for ExecuteCommandTool."""
+
+    skill_name: str = Field(


Not sure about requiring a skill name for executing a command. Skills are not executable programs like tools, but are a set of knowledges, scripts and resource for doing something. It's the LLM/agent that learns a skill and perform actions. You cannot execute a skill, nor saying an action belongs to a certain skill.

github-actions bot added doc-needed Your PR changes impact docs. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. and removed doc-needed Your PR changes impact docs. labels Mar 26, 2026

wenjin272 force-pushed the skills-python branch from 80caeb0 to 2352ecd Compare March 27, 2026 02:00

wenjin272 changed the title ~~Skills python~~ Support agent skills in python Apr 1, 2026

wenjin272 changed the title ~~Support agent skills in python~~ [api][integration] Support agent skills in python Apr 1, 2026

github-actions bot added doc-needed Your PR changes impact docs. and removed doc-needed Your PR changes impact docs. labels Apr 1, 2026

wenjin272 added 4 commits April 7, 2026 17:51

[test] Ignore some pydocstyle rules for test files.

c2d60f2

[api] Inject output format prompt after the first system prompt for R…

50757f7

…eAct agent.

[api] Extract resource context.

35d5952

[feature][python] Support agent skills.

693b65c

wenjin272 force-pushed the skills-python branch from 2352ecd to 693b65c Compare April 7, 2026 14:31

alnzng reviewed Apr 13, 2026

View reviewed changes

xintongsong reviewed Apr 14, 2026

View reviewed changes

wenjin272 mentioned this pull request Apr 14, 2026

[api][runtime] Support Mem0 based Long-Term Memory in Python. #629

Open

3 tasks

		from flink_agents.runtime.skill.skill_repository import SkillRepository


		class RegisteredSkill:

Conversation

wenjin272 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of change

Tests

API

Documentation

Uh oh!

wenjin272 commented Mar 26, 2026

Uh oh!

alnzng 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wenjin272 commented Mar 26, 2026 •

edited

Loading