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.
- Automatic Discovery: Finds all packages with type
ai-agent-skill - AGENTS.md Generation: Creates XML skill index compatible with openskills
- CLI Commands:
composer list-skillsandcomposer read-skillfor 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
composer require netresearch/composer-agent-skill-pluginDuring 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.
For CI/CD or non-interactive environments, pre-authorize the plugin in your composer.json:
{
"config": {
"allow-plugins": {
"netresearch/composer-agent-skill-plugin": true
}
}
}Install any package with type ai-agent-skill:
composer require vendor/database-analyzer-skillThe plugin automatically:
- Discovers skill packages during
composer installorcomposer update - Generates/updates
AGENTS.mdin your project root - Registers skills in XML format for AI agent consumption
AI agents automatically discover skills via AGENTS.md:
# List all available skills
composer list-skills
# Read a specific skill
composer read-skill database-analyzer$ 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.$ 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-analyzerThe Base Directory is the directory containing SKILL.md, used as the root for resolving bundled resources like references/, scripts/, and assets/.
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 dependencies3. Publish to Packagist:
git tag 1.0.0
git push --tagsFor 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"
]
}
}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.
Skills must follow the Claude Code SKILL.md specification:
---
name: skill-name # lowercase, numbers, hyphens only (max 64 chars)
description: Clear description of functionality and triggers (max 1024 chars)
------
name: my-skill
description: What it does and when to use it
allowed-tools: [Read, Grep, Glob] # Claude Code only
---- 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 (
---)
No configuration needed. Plugin looks for SKILL.md in package root:
vendor/my-skill/
├── composer.json
├── SKILL.md ← Auto-discovered
└── src/
{
"extra": {
"ai-agent-skill": "custom/path/skill.md"
}
}{
"extra": {
"ai-agent-skill": [
"skills/skill-one.md",
"skills/skill-two.md",
"docs/skill-three.md"
]
}
}[WARNING] No AI agent skills found in installed packages.
Solution: Install packages with "type": "ai-agent-skill" in their composer.json.
[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.
[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.
[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.
[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.
[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.
- Plugin hooks into
composer installandcomposer updateevents - Finds all packages with type
ai-agent-skill - Reads each package's
composer.jsonfor skill paths - Parses SKILL.md files and validates frontmatter
- Generates XML skill registry in
AGENTS.md
<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>- 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
- 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+
# Run all tests
./vendor/bin/phpunit
# Run with coverage
./vendor/bin/phpunit --coverage-text
# Run specific test
./vendor/bin/phpunit tests/Unit/SkillDiscoveryTest.php# 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=yessrc/
├── 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
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
- PSR-12 coding style
- PHPStan level 8
- 100% type coverage
- Comprehensive tests (>80% coverage)
This project is licensed under the MIT License - see the LICENSE file for details.
Inspired by openskills - Universal AI Agent Skills for standardized skill distribution across development environments.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with ❤️ by Netresearch