Skip to main content

Agent Skills System

We have modernized our AI Agent Skills infrastructure to follow the open standard defined by AgentSkills.io. This shift moves us from a flat structure of disconnected scripts to encapsulated, portable, and version-controlled skill packages.

What are Agent Skills?​

Agent Skills provide our AI agents with specialized, domain-specific knowledge and repeatable workflows. Instead of bloating the agent's general context with every possible instruction, we package these capabilities into individual, self-contained folders.

This enables Progressive Disclosure:

  1. Discovery: Agents only load the name and description of all skills down at startup.
  2. Activation: When a task matches the description, the agent dynamically loads the full instructions.
  3. Execution: The agent follows the instructions and executes the bundled scripts.

Directory Structure​

All skills are now stored under the agent-skills/ directory at the project root. Each skill encapsulates its metadata, instructions, and executable scripts.

agent-skills/
├── skill-name/
│   ├── SKILL.md          # Required: Metadata (YAML) + AI instructions
│   ├── scripts/          # Optional: Executable code (PHP, JS, Python)
│   ├── references/       # Optional: Detailed documentation loaded on demand
│   └── assets/           # Optional: Static resources, JSON templates

The SKILL.md File​

The heart of every skill is the SKILL.md file. It uses mandatory YAML frontmatter to allow the agent to discover it:

---
name: find-docs
description: Searches the WordPress database for documentation pages. Use this when you need to locate existing documentation slugs.
---

Below the frontmatter, we define the actual Markdown instructions for the agent. This content typically includes:

  • Available Scripts: What scripts are bundled and what they do.
  • Usage/Workflow: A procedural checklist (Plan-Validate-Execute) showing the agent exact terminal commands to run.
  • Gotchas: Known edge cases or common mistakes the agent should avoid (e.g., Docker container paths, Soft deletes in DB).

Script Design Guidelines​

Our agent-executed scripts (inside the scripts/ folder) must be designed for non-interactive use:

  • No Interactive Prompts: Scripts must accept all input via CLI flags (--input, --format) and never wait for a TTY input prompt.
  • Structured Output: Data meant to be parsed by the agent should be printed in structured formats like JSON to stdout.
  • Clean Diagnostics: Progress logs, warnings, and error messages should be routed to stderr. This separates the data from the diagnostics.
  • Helpful Errors: If an argument is missing, the script should output clear usage instructions so the agent can self-correct and try again.

Creating a New Skill​

When adding a new capability (e.g., processing images, injecting lambo chunks, flushing caches):

  1. Create a new folder in agent-skills/ with a hyphenated name.
  2. Add a SKILL.md with proper YAML frontmatter (name and description).
  3. Place the operational code inside agent-skills/<skill-name>/scripts/.
  4. Keep the main SKILL.md concise (under 500 lines) and push heavy details into references/.

By strictly enforcing this structure, our agents—whether they are Writer, Docser, or Tester—can safely discover and execute complex workflows without cluttering their main prompts or suffering from hallucinated terminal commands.