SkillBound Agent

SkillBound Agent is a skill-defined agent runtime. Skills define capabilities and boundaries; the runtime enforces them.

The runtime loads selected skill packages, exposes their declared capabilities to an agent, and executes only the behavior defined by those skills. Domain behavior belongs in skill packages, not in the runtime.

example-skills/flink-intelligent-ops is included as a reference implementation that shows how a production-oriented skill can describe tools, constrain command execution, and guide an agent through operational workflows.

Design Philosophy

Traditional agents often get broad access to tools and APIs, then rely on prompts to behave safely. SkillBound reverses that relationship:

Skill defines behavior.
Runtime enforces boundaries.
Agent reasons inside the selected skill surface.

A skill is the product boundary. It owns instructions, metadata, command catalogs, schemas, scripts, references, and safety rules. The runtime is intentionally thin: it loads skills, authorizes access, exposes declared tools, executes skill-defined commands, streams results, and records audit history.

The runtime should not contain hidden domain workflows. Flink operations, SQL development, data analysis, and any other domain capability must live in reusable skill packages.

Core Ideas

• Skill-defined execution: the agent can only use capabilities declared by selected skills.
• Runtime-enforced boundaries: command execution is validated, recorded, and streamed back to the UI.
• Domain-neutral runtime: product-specific behavior is packaged as skills.
• Auditable operations: tool calls, command lifecycle events, outputs, and session history are persisted.
• Reusable capability packages: skills can be built, reviewed, shared, uploaded, authorized, and selected independently.

Related Repositories

• skillbound-agent: this runtime repository.
• skillbound-skills: reusable skills that define agent capabilities, commands, schemas, scripts, references, and safety boundaries.

Repository Layout

agent_service/                 FastAPI backend and agent runtime
frontend/                      Vite + React + TypeScript UI
scripts/                       MySQL schema and bootstrap helpers
example-skills/                Example skill packages
docs/                          User and contributor documentation
tests/                         Backend pytest suite

Local runtime data is written under var/ and ignored by git. Uploaded skills are stored under var/skills/; example skills live under example-skills/.

Documentation

• Quick Start
• Configuration
• Creating Skills
• Operations Guide
• Contributing

Requirements

• Python 3.10+
• Node.js 18+
• MySQL 8.x

SQLite is not supported.

Quick Start

Create the backend environment:

python3 -m venv venv
venv/bin/python -m pip install --upgrade pip
venv/bin/python -m pip install -r requirements.txt

Initialize MySQL:

MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root ./scripts/init_mysql_schema.sh

Create or choose a MySQL user that can access the skill_agent database, then set runtime configuration:

export DATABASE_URL='mysql+pymysql://skill_agent:skill_agent@127.0.0.1:3306/skill_agent'
export AUTH_SECRET='change-me'

Start the backend:

venv/bin/python -m agent_service.main

Start the frontend:

cd frontend
npm install
npm run dev

Vite proxies /api and /health to the backend.

Skill Packages

A skill upload is a zip file containing one top-level skill directory:

my-skill/
  SKILL.md
  skill.yaml
  schemas/
  references/
  scripts/

SKILL.md explains when and how the agent should use the skill. skill.yaml declares metadata, tools, commands, and schemas. See Creating Skills for the package contract.

Verification

Backend checks:

venv/bin/python -m compileall agent_service tests
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 venv/bin/python -m pytest tests -q

Set MYSQL_TEST_DATABASE_URL if your test database is different from the default:

export MYSQL_TEST_DATABASE_URL='mysql+pymysql://skill_agent:skill_agent@127.0.0.1:3306/skill_agent_test'

Frontend checks:

cd frontend
npm run test -- --run
npm run build

Scope Boundaries

• In scope: skill upload, package validation, storage, authorization, selection, loading, tool discovery, skill-defined execution, streaming results, audit records, and conversation history around skill execution.
• Out of scope: domain-specific workflows that are not defined by a selected skill, direct product integrations in platform code, and platform-side shortcuts that bypass skill commands or scripts.
• MySQL schema is maintained as a direct SQL init script; there is no Alembic migration chain yet.

References

• Skill format reference: aliyun/alibabacloud-aiops-skills: alibabacloud-flink-workspace-ops
• Flink operations and deployment capability reference: apache/incubator-streampark

License

Apache-2.0.