SKILL.md: The Declarative Blueprint for Autonomous Agent Behaviour

Prompt engineering is duct tape. It works for demos and prototypes, but the moment you need reproducible, versionable, deployable agent behaviour, you need something more structured. We developed the SKILL.md framework: a declarative specification format where each autonomous capability is defined in a single markdown file that the agent engine can parse, route, and execute as a complete ReAct loop.

A SKILL.md file is not a prompt. It is a contract between the human operator and the agent engine. It declares the skill's identity, required tools, input schema, execution steps, success criteria, and failure recovery procedures. The SkillRouter reads these files at boot time and builds an index. When a user issues a natural language command, the TaskEngine parses intent and the SkillRouter matches it to the highest-confidence skill definition.

# SKILL.md — pugongying-kol-search v4.0
name: "pugongying-kol-search"
version: "4.0"
category: "operations"
description: "Search and evaluate KOLs on Pugongying platform"

triggers:
  - "find KOLs"
  - "search bloggers"
  - "scout influencers on xiaohongshu"

required_tools:
  - browser_navigate
  - browser_fill_form
  - browser_extract_table
  - ai_evaluate

input_schema:
  keywords: string[]
  min_followers: number
  category_filter: string[]

steps:
  1: "Navigate to pugongying.xiaohongshu.com"
  2: "Apply search filters from input_schema"
  3: "Paginate and extract KOL data into structured table"
  4: "Run AI evaluation on each candidate"
  5: "Return ranked results via WebSocket"

failure_recovery:
  login_required: "Trigger BrowserLock, wait for manual auth"
  rate_limited: "Exponential backoff, max 3 retries"
  stale_page: "Force refresh, re-acquire lock"

Because skills are files, they are inherently versionable. When v3.2 of the KOL search skill starts failing due to a platform UI change, you do not debug a tangled prompt chain. You diff v3.2 against v4.0 and see exactly which steps changed. You can roll back. You can A/B test two skill versions simultaneously. This is infrastructure-grade agent management, not artisanal prompt craft.

The most powerful pattern in the framework is the skill-creator skill—a meta-skill that generates new SKILL.md files from natural language descriptions. An operator describes a new workflow in plain Chinese or English, and the skill-creator agent produces a valid, tested SKILL.md file ready for deployment. This closes the loop: the system can extend its own capabilities without developer intervention.

• ·Declarative, not imperative: Skills describe WHAT to achieve, not HOW to click.
• ·Self-documenting: The SKILL.md file IS the documentation.
• ·Hot-reloadable: New skills deploy without restarting the agent engine.
• ·Composable: Complex workflows chain multiple skills in sequence.

The discipline of making AI agents useful in production is shifting. Prompt engineering optimises a single interaction. Skill engineering optimises an entire autonomous workflow—from trigger to execution to failure recovery to output delivery. The teams that master this shift will own the next generation of AI-native business infrastructure. The rest will still be tweaking system prompts.