MCP Skills

Since quiqqer/ai-mcp 1.5.0, QUIQQER packages can provide MCP skills. A skill is a Markdown instruction file that an AI client can discover and load through the QUIQQER MCP endpoint.

Use skills for reusable, package-specific guidance such as implementation workflows, content editing rules, operational checks, or project conventions. Skills do not execute code. They provide instructions and context for AI clients.

How Skills Are Exposed

Installed packages register skill files through Skill Providers. The MCP server collects those registrations and exposes them through normal MCP resources and tool fallbacks.

Resources:

Resource	Purpose
quiqqer://mcp/skills	Lists available skills.
quiqqer://mcp/skill/{name}	Returns one skill by name.
quiqqer://mcp/skill/get/{name}	Returns one skill by name through an explicit get-style resource.

Tool fallbacks:

Tool	Purpose
quiqqer_skill_list	Lists available skills.
quiqqer_skill_get	Returns one skill by name.
quiqqer_mcp_skill_list	Lists available skills through an MCP-namespaced alias.
quiqqer_mcp_skill_get	Returns one skill through an MCP-namespaced alias.

Example direct lookup:

quiqqer_mcp_skill_get name=quiqqer_bricks_create_landing_pages

The skill list can be filtered by category when the client calls a list tool with a category argument.

Skill File Layout

Place skill files in the package under this structure:

skills/
+-- developer/
    +-- vendor_package_developer.md

The required path format is:

skills/<category>/<skill_name>.md

The file name must match the skill name plus .md. The category directory must match the category frontmatter value.

Each skill file starts with YAML frontmatter:

---
name: vendor_package_developer
description: Use when developing or debugging Vendor Package integrations.
category: developer
---

# Vendor Package Developer

Use this skill when working with Vendor Package code and integrations.

Required frontmatter fields:

Field	Value
name	Unique lower-snake-case identifier with lowercase letters, digits, and underscores.
description	Short client-facing description that explains when to use the skill.
category	One of the supported skill categories.

Supported categories:

• developer
• user
• admin
• content
• system

Use names that include the package or module context, for example quiqqer_bricks_create_landing_pages. Skill names are global within the MCP skill repository.

Skill Provider

Create a provider class that implements QUI\AI\MCP\Skill\SkillProviderInterface:

<?php

namespace Vendor\Package;

use QUI\AI\MCP\Skill\SkillProviderInterface;
use QUI\AI\MCP\Skill\SkillRepository;

final class MySkillProvider implements SkillProviderInterface
{
    public function registerSkills(SkillRepository $repository): void
    {
        $repository->addFromMarkdownFile(
            dirname(__DIR__, 1) . '/skills/developer/vendor_package_developer.md'
        );
    }
}

Register the provider in package.xml:

<provider>
    <mcpSkill src="\Vendor\Package\MySkillProvider" />
</provider>

During setup, QUIQQER imports the provider declaration. Run setup after adding or changing a Skill Provider:

./console setup

Response Shape

Skill list entries include metadata and the direct skill resource:

{
  "name": "vendor_package_developer",
  "description": "Use when developing or debugging Vendor Package integrations.",
  "category": "developer",
  "package": "vendor/package",
  "provider": "Vendor\\Package\\MySkillProvider",
  "resource": "quiqqer://mcp/skill/vendor_package_developer"
}

Single skill responses include the same metadata plus content, which contains the Markdown body of the skill.

Reference Skill

quiqqer/ai-mcp provides the reference skill quiqqer_ai_mcp_create_skills in:

skills/developer/quiqqer_ai_mcp_create_skills.md

It describes how agents should create and register additional QUIQQER MCP skills.

Design Rules

• Keep each skill focused on one recurring workflow.
• Write instructions for AI clients, not package marketing text.
• Use the smallest useful context and link only direct reference files.
• Include validation commands when the workflow changes code or content.
• Do not put API tokens, credentials, customer secrets, or internal deployment details into skill files.
• Do not add custom MCP methods such as skills/list; use the standard resources and tool fallbacks.