refactor(skill)!: replace fixed skill metadata with map-based metadata and remove SkillBox template-based constructors

[fang-tech]

AgentScope-Java Version

1.0.11

Description

fix #1184 close #1234 dup #1082

Summary

• replace fixed skill metadata fields with a dynamic Map<String, Object> model across parsing, storage, and prompt rendering
• preserve nested YAML frontmatter metadata and round-trip it through filesystem and MySQL repositories
• switch skill prompt rendering to the built-in XML metadata format and tighten metadata validation behavior

Breaking Changes

• removed SkillBox(String instruction, String template)
• removed template-based skill prompt customization from SkillBox-related APIs; custom skill prompts now support instruction-based customization only
• updated SkillBox constructor parameter lists to remove the template argument
• skill prompt generation no longer uses caller-provided custom templates for skill metadata rendering
• skill metadata is now modeled as dynamic Map<String, Object> instead of relying on a fixed top-level field set
• code that depended on fixed metadata fields, fixed prompt template structure, or old constructor signatures must be updated

Behavior Changes

• YAML frontmatter parsing now preserves nested Map / List metadata instead of flattening or stringifying complex values
• required metadata fields such as name and description must now be non-blank strings
• prompt XML rendering now skips metadata entries whose values are null
• skill prompts always expose skill-id
• prompt metadata exposure can now be configured to expose all metadata or only core fields

Storage Changes

• filesystem skill persistence now round-trips full metadata instead of saving only limited core fields
• MySQL skill storage now supports metadata_json for new schema creation
• legacy MySQL tables remain readable and writable without automatic schema migration, but they fall back to legacy behavior when metadata_json is absent

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[Copilot]

Pull request overview

This PR refactors the skill pipeline so that rich YAML frontmatter metadata (including nested structures and insertion order) is preserved end-to-end: parsing, prompt rendering, filesystem persistence, and (optionally) MySQL storage via a metadata_json column.

Changes:

• Replace fixed skill fields with ordered, nested metadata (Map<String, Object>) and update parsing/generation to use SnakeYAML.
• Render skill metadata into agent prompts as XML, with an option to expose only core fields (name, description, skill-id).
• Add MySQL metadata_json support with runtime schema detection and legacy fallback behavior.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/zh/task/agent-skill.md	Documents rich frontmatter metadata, XML prompt rendering, and metadata exposure control.
docs/en/task/agent-skill.md	English equivalent documentation updates for metadata + XML prompts + exposure control.
agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkill.java	Moves to metadata-centric model and exposes metadata getters/builder APIs.
agentscope-core/src/main/java/io/agentscope/core/skill/AgentSkillPromptProvider.java	Switches skill prompt entries to XML rendering from metadata with exposure control.
agentscope-core/src/main/java/io/agentscope/core/skill/SkillBox.java	Updates prompt provider wiring and adds setExposeAllSkillMetadata.
agentscope-core/src/main/java/io/agentscope/core/skill/util/MarkdownSkillParser.java	Replaces custom YAML parser with SnakeYAML + normalization + size limits.
agentscope-core/src/main/java/io/agentscope/core/skill/util/SkillFileSystemHelper.java	Persists full metadata to SKILL.md frontmatter during save.
agentscope-core/src/main/java/io/agentscope/core/skill/util/SkillUtil.java	Creates AgentSkill from parsed metadata instead of only name/description fields.
agentscope-core/pom.xml	Adds org.yaml:snakeyaml dependency.
agentscope-extensions/.../MysqlSkillRepository.java	Adds metadata_json support with schema detection and legacy fallback behavior.
agentscope-extensions/.../MysqlSkillRepositoryTest.java	Adds coverage for metadata_json support + legacy fallback.
agentscope-core/src/test/... (multiple files)	Updates/extends tests for metadata preservation, immutability expectations, and XML prompt behavior.

[codecov]

Codecov Report

❌ Patch coverage is 81.96078% with 46 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...gentscope/core/skill/util/MarkdownSkillParser.java	76.47%	11 Missing and 5 partials ⚠️
...e/skill/repository/mysql/MysqlSkillRepository.java	80.59%	6 Missing and 7 partials ⚠️
...gentscope/core/skill/AgentSkillPromptProvider.java	85.00%	5 Missing and 4 partials ⚠️
...main/java/io/agentscope/core/skill/AgentSkill.java	89.47%	3 Missing and 1 partial ⚠️
.../java/io/agentscope/core/skill/util/SkillUtil.java	76.92%	1 Missing and 2 partials ⚠️
...ntscope/core/skill/util/SkillFileSystemHelper.java	75.00%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[LearningGp]

This PR introduces breaking changes. I suggest updating the PR title and description to include more details, specifically regarding the removal of the SkillBox(String instruction, String template) constructor and other parameter list updates.

[fang-tech]

This PR introduces breaking changes. I suggest updating the PR title and description to include more details, specifically regarding the removal of the SkillBox(String instruction, String template) constructor and other parameter list updates.

Done

[LearningGp]

LGTM