Skill Agent

Author: liux297 · [email protected]
Version: 0.2.5 | Type: Tool Plugin | License: Apache-2.0
Repository: https://github.com/liux297/skill_agent

---

Introduction

Skill Agent is a general-purpose tool plugin built on the Skill Progressive Disclosure pattern, inspired by the OpenClaw and Hermes agent architectures. It treats the local directory as a modular toolbox: the model reads a skill index first, then loads the relevant manual on demand, and finally reads reference files or runs scripts only when necessary — delivering text or files as the final output.

---

What's New in v0.2.5

• Custom Variables () — Inject JSON key-value pairs into the agent context. Skills access them via . Supports template replacement in SKILL.md and environment variable injection for subprocess commands.
• Verbose Mode () — Toggle between detailed tool execution progress (for debugging) and clean user-facing output (for production).
• Custom System Prompt () — Override or extend the default agent behavior instructions.
• Optimized Progressive Disclosure — When SKILL.md already specifies an executable entry point, the agent executes directly without redundant calls.
• Smart Command Coercion — Automatically converts string commands to arrays and strips backticks accidentally copied from Markdown code blocks.
• Structured Output Formatting — JSON results from commands are automatically converted to structured natural-language summaries.
• Enhanced Diagnostics — Improved error messages for DNS/network failures and empty stdout to help the LLM self-diagnose issues.
• Model Capability Detection — Adaptive detection of model function-calling support, with automatic fallback between Function Calling and JSON protocol (inspired by OpenClaw/Hermes).
• Unified Tool Execution Pipeline — Single execution path eliminates duplicate FC/JSON logic.
• Token-Aware Context Compaction — Smart context compression based on token estimation with automatic recovery from context overflow.
• Smart JSON Compression — Intelligent JSON summarization replaces naive truncation.
• Streaming Output with Protocol Filtering — Real-time natural-language streaming while internal JSON protocol messages are hidden from users.
• Step-by-Step Process Visualization — Categorized icons, step numbering, and configurable verbose toggle.
• Command Whitelist Sandbox — Secure script execution within a configurable command whitelist.

---

Use Cases

• Integrate Skills and constrain/strengthen the model using "manual (SKILL.md) + file structure + scripts"
• Show progress messages and return generated files as tool outputs
• Package capabilities as reusable skill folders (References, Scripts, etc.) instead of hard-coding everything in prompts
• Inject runtime context (user identity, team ID, etc.) into skills via

---

Features

• Progressive Disclosure: skill index → read → read files / run commands as needed
• File Delivery: all files in the temp session directory are returned when the agent finishes
• Free Execution: the agent can run any whitelisted command (read/write files, execute scripts, etc.)
• Controllable Memory: configurable memory turns and max step depth
• Custom Variables: inject runtime context via templates and environment variables
• Verbose Mode Toggle: switch between debug-level detail and clean user-facing output

---

Tool Parameters

This plugin provides two tools:

• Skill Manager — Manages the local skills directory (list / add / delete / download skills).
  [Image blocked: Skill Manager]
• agent_skill — A general agent that executes stored skills.
  [Image blocked: agent_skill]

The agent_skill tool accepts the following parameters:

The parameter accepts a JSON object of key-value pairs that will be injected into the agent context. Skills can access these variables via , making it easy to pass user identity, team info, or other runtime context to skills.

---

How to Use (in Dify)

Step 1: Install this plugin from the Marketplace (or upload the file)

Step 2: For self-hosted deployments, set in Dify's to your Dify address, otherwise Dify cannot fetch uploaded files

Step 3: Build your workflow as shown below
[Image blocked: Workflow]

Step 4: Manage skills (upload skill packages as zip files)
[Image blocked: Manage Skills]

Step 5: Chat with Skill Agent
[Image blocked: Chat 1]
[Image blocked: Chat 2]

---

Skill Standard

• Every skill must include (YAML frontmatter supported: , )
• can define trigger conditions, workflow, required reference reads, commands to run, and deliverable specs
• Skills can use placeholders that are replaced by values from

---

Changelog

v0.2.5 (current):

1. JSON key-value injection with template replacement and environment variable pass-through
2. mode toggle for debug or user-facing output
3. parameter to override default agent instructions
4. Optimized progressive disclosure: skip redundant file listing when entry point is specified
5. Auto string-to-array command coercion with backtick cleanup
6. Auto JSON-to-natural-language structured summary
7. Enhanced diagnostics for DNS/network failures and empty stdout
8. Adaptive model capability detection (FC / JSON protocol auto-switch, OpenClaw/Hermes inspired)
9. Unified tool execution pipeline eliminating duplicate FC/JSON paths
10. Token-aware context compaction with automatic overflow recovery
11. Smart JSON compression replacing naive truncation
12. Real-time streaming output with internal protocol filtering
13. Step-by-step process visualization with categorized icons and step numbering
14. Command whitelist sandbox for secure script execution

Earlier versions: Streaming output, multi-turn conversations, file memory, file uploads, auto dependency installation, skill management, and the core progressive disclosure architecture.

---

FAQ

1. Installation issues
If installation fails with network access available, try switching Dify's pip mirror for better dependency downloads. In intranet environments, install via an offline package (contact the author).

2. File transfer issues
If uploading/downloading files fails (wrong URL, download timeout, etc.), check whether Dify's has set correctly and matches your Dify address.

3. No output from skill_agent
Make sure your model and provider plugin support function calling.

4. Skill invocation issues
The more complete your skill is, the more smoothly the agent can invoke it. Ensure your skill materials and scripts are not missing. For Node.js script skills, install Node.js in the Dify container first.

5. Using custom_variables
Pass a JSON string like . Reference variables as in SKILL.md or via environment variables (auto uppercased: ).

---

Author & Contact

• Author: liux297
• Email: [email protected]
• Repository: https://github.com/liux297/skill_agent

License

Copyright (c) 2026 liux297

Licensed 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

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.