README

A Composer plugin that enables universal AI agent skill distribution and management for PHP projects. Automatically discovers, registers, and manages AI agent skills from Composer packages, providing a standardized way for the PHP ecosystem to share agent capabilities.

Features

Automatic Discovery: Finds all packages with type ai-agent-skill
AGENTS.md Generation: Creates XML skill index compatible with openskills
CLI Commands: composer list-skills and composer read-skill for skill inspection
Convention Over Configuration: Works out of the box with zero configuration
Progressive Disclosure: Lightweight index, full details on demand
Security First: Rejects absolute paths, validates all skill metadata
Multiple Skills Per Package: Support for both single and multi-skill packages

Installation

composer require netresearch/composer-agent-skill-plugin

During installation, Composer will prompt you to authorize the plugin:

netresearch/composer-agent-skill-plugin contains a Composer plugin which is currently not in your allow-plugins config.
Do you trust "netresearch/composer-agent-skill-plugin" to execute code and wish to enable it now? [y,n,d,?]

Choose y to allow the plugin to activate.

Non-Interactive Installation

For CI/CD or non-interactive environments, pre-authorize the plugin in your composer.json:

{
    "config": {
        "allow-plugins": {
            "netresearch/composer-agent-skill-plugin": true
        }
    }
}

Quick Start

1. Install Skill Packages

Install any package with type ai-agent-skill:

composer require vendor/database-analyzer-skill

2. Skills Auto-Register

The plugin automatically:

Discovers skill packages during composer install or composer update
Generates/updates AGENTS.md in your project root
Registers skills in XML format for AI agent consumption

3. Use Skills

AI agents automatically discover skills via AGENTS.md:

# List all available skills
composer list-skills

# Read a specific skill
composer read-skill database-analyzer

Usage

List Available Skills

$ composer list-skills

Available AI Agent Skills:

  database-analyzer        vendor/db-skill               1.2.0
  oro-bundle-helper        vendor/oro-skill              1.0.0
  symfony-security         vendor/symfony-security       2.1.0

3 skills available. Use 'composer read-skill <name>' for details.

Read Skill Details

$ composer read-skill database-analyzer

Reading: database-analyzer
Package: vendor/db-skill v1.2.0
Base Directory: vendor/vendor/db-skill

---
name: database-analyzer
description: Analyze and optimize database schemas and relationships
---

# Database Analyzer Skill

[Full SKILL.md content with instructions and examples]

Skill read: database-analyzer

The Base Directory is the directory containing SKILL.md, used as the root for resolving bundled resources like references/, scripts/, and assets/.

Creating Skill Packages

Basic Skill Package

1. Create composer.json:

{
  "name": "vendor/my-skill",
  "description": "My awesome AI agent skill",
  "type": "ai-agent-skill",
  "license": "MIT",
  "require": {
    "php": "^8.2"
  }
}

2. Create SKILL.md in package root:

---
name: my-skill
description: Brief description of what this skill does and when to use it
---

# My Skill

## Instructions

Step-by-step guidance for using this skill...

## Examples

Example 1: How to use feature X
Example 2: How to handle scenario Y

## Requirements

- PHP 8.2+
- Any other dependencies

3. Publish to Packagist:

git tag 1.0.0
git push --tags

Multi-Skill Package

For packages containing multiple skills, configure paths in extra.ai-agent-skill:

{
  "name": "vendor/database-tools",
  "type": "ai-agent-skill",
  "require": {
    "netresearch/composer-agent-skill-plugin": "*"
  },
  "extra": {
    "ai-agent-skill": [
      "skills/analyzer/SKILL.md",
      "skills/optimizer/SKILL.md",
      "skills/validator/SKILL.md"
    ]
  }
}

Custom Skill Path

For a single skill in a non-standard location:

{
  "name": "vendor/custom-skill",
  "type": "ai-agent-skill",
  "require": {
    "netresearch/composer-agent-skill-plugin": "*"
  },
  "extra": {
    "ai-agent-skill": "docs/agent-skill.md"
  }
}

Security Note: Only relative paths from package root are allowed. Absolute paths are rejected.

SKILL.md Schema

Skills must follow the Claude Code SKILL.md specification:

Required Frontmatter

---
name: skill-name          # lowercase, numbers, hyphens only (max 64 chars)
description: Clear description of functionality and triggers (max 1024 chars)
---

Optional Frontmatter

---
name: my-skill
description: What it does and when to use it
allowed-tools: [Read, Grep, Glob]  # Claude Code only
---

Validation Rules

Name format: ^[a-z0-9-]{1,64}$ (lowercase alphanumeric and hyphens)
Name length: Maximum 64 characters
Description length: Maximum 1024 characters
YAML syntax: Valid YAML with proper delimiters (---)

Configuration Options

Default (Convention)

No configuration needed. Plugin looks for SKILL.md in package root:

vendor/my-skill/
├── composer.json
├── SKILL.md          ← Auto-discovered
└── src/

Custom Single Skill

{
  "extra": {
    "ai-agent-skill": "custom/path/skill.md"
  }
}

Multiple Skills

{
  "extra": {
    "ai-agent-skill": [
      "skills/skill-one.md",
      "skills/skill-two.md",
      "docs/skill-three.md"
    ]
  }
}

Troubleshooting

No Skills Found

[WARNING] No AI agent skills found in installed packages.

Solution: Install packages with "type": "ai-agent-skill" in their composer.json.

Duplicate Skill Names

[vendor/tools-b] Duplicate skill name 'database-analyzer' (already defined by vendor/tools-a).
                 Using skill from vendor/tools-b (last one wins).

Behavior: Last package wins. Consider renaming skills to avoid conflicts.

Invalid Frontmatter

[vendor/broken-skill] Invalid frontmatter in 'SKILL.md': Missing required field: 'description'

Solution: Ensure SKILL.md has both name and description fields in valid YAML format.

Malformed YAML

[vendor/broken-yaml] Malformed YAML in 'SKILL.md':
                     A colon cannot be used in an unquoted mapping value at line 3

Solution: Fix YAML syntax. Use spaces (not tabs), quote values with colons.

Missing SKILL.md

[vendor/missing-skill] SKILL.md not found at 'SKILL.md'.
                       Expected SKILL.md in package root (convention).

Solution: Create SKILL.md in package root or configure extra.ai-agent-skill path.

Absolute Path Rejected

[vendor/unsafe-config] Absolute paths not allowed in 'extra.ai-agent-skill'.
                       Use relative paths from package root.

Solution: Use relative paths like "skills/analyzer.md" instead of /absolute/path.

How It Works

Discovery Process

Plugin hooks into composer install and composer update events
Finds all packages with type ai-agent-skill
Reads each package's composer.json for skill paths
Parses SKILL.md files and validates frontmatter
Generates XML skill registry in AGENTS.md

AGENTS.md Structure

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.

How to use skills:
- Invoke: Bash("composer read-skill <skill-name>")
- The skill content will load with detailed instructions
- Base directory provided in output for resolving bundled resources
</usage>

<available_skills>

<skill>
<name>database-analyzer</name>
<description>Analyze and optimize database schemas</description>
<location>vendor/vendor/db-skill</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

Progressive Disclosure

AGENTS.md: Lightweight index with skill names and descriptions
read-skill: Full SKILL.md content loaded on demand
Benefits: Fast discovery, reduced context size, on-demand details

Requirements

PHP 8.2 or higher
Composer 2.1 or higher
Symfony YAML Component 5.4+, 6.0+, or 7.0+
Symfony Console Component 5.4+, 6.0+, or 7.0+

Development

Running Tests

# Run all tests
./vendor/bin/phpunit

# Run with coverage
./vendor/bin/phpunit --coverage-text

# Run specific test
./vendor/bin/phpunit tests/Unit/SkillDiscoveryTest.php

Code Quality

# PHPStan static analysis (level 8)
./vendor/bin/phpstan analyse

# PHP CS Fixer (PSR-12)
./vendor/bin/php-cs-fixer fix --allow-risky=yes

# Check without fixing
./vendor/bin/php-cs-fixer fix --dry-run --allow-risky=yes

Project Structure

src/
├── Commands/
│   ├── ListSkillsCommand.php    # composer list-skills
│   └── ReadSkillCommand.php     # composer read-skill
├── Exceptions/
│   └── InvalidSkillException.php
├── AgentsMdGenerator.php         # AGENTS.md generation
├── CommandCapability.php         # Command registration
├── SkillDiscovery.php            # Package discovery
└── SkillPlugin.php               # Main plugin class

tests/
├── Unit/                         # Unit tests
├── Integration/                  # Integration tests
└── Fixtures/                     # Test fixtures

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (./vendor/bin/phpunit)
Run static analysis (./vendor/bin/phpstan analyse)
Fix code style (./vendor/bin/php-cs-fixer fix --allow-risky=yes)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

PSR-12 coding style
PHPStan level 8
100% type coverage
Comprehensive tests (>80% coverage)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Inspiration

Inspired by openskills - Universal AI Agent Skills for standardized skill distribution across development environments.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ by Netresearch

netresearch / composer-agent-skill-plugin

Maintainers

Details