{"id":36934801,"url":"https://github.com/netresearch/composer-agent-skill-plugin","last_synced_at":"2026-02-15T13:11:26.483Z","repository":{"id":326061000,"uuid":"1103694226","full_name":"netresearch/composer-agent-skill-plugin","owner":"netresearch","description":"Composer plugin enabling universal Agent Skill distribution and management for PHP projects","archived":false,"fork":false,"pushed_at":"2026-01-22T21:03:46.000Z","size":140,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-23T13:55:58.927Z","etag":null,"topics":["agent-skills","ai-agent","claude-code","composer-plugin","open-standard","openskills","php","skills"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netresearch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-25T08:00:19.000Z","updated_at":"2026-01-23T08:38:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/netresearch/composer-agent-skill-plugin","commit_stats":null,"previous_names":["netresearch/composer-agent-skill-plugin"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/netresearch/composer-agent-skill-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fcomposer-agent-skill-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fcomposer-agent-skill-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fcomposer-agent-skill-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fcomposer-agent-skill-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netresearch","download_url":"https://codeload.github.com/netresearch/composer-agent-skill-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fcomposer-agent-skill-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29479221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agent","claude-code","composer-plugin","open-standard","openskills","php","skills"],"created_at":"2026-01-13T09:53:29.411Z","updated_at":"2026-02-15T13:11:26.478Z","avatar_url":"https://github.com/netresearch.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Composer AI Agent Skill Plugin\n\nA 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.\n\n[![CI](https://github.com/netresearch/composer-agent-skill-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/netresearch/composer-agent-skill-plugin/actions/workflows/ci.yml)\n[![Tests](https://img.shields.io/badge/tests-31%20passing-success)](tests/)\n[![PHPStan](https://img.shields.io/badge/PHPStan-level%208-success)](phpstan.neon)\n[![PHP Version](https://img.shields.io/badge/php-%5E8.2-blue)](composer.json)\n[![Symfony](https://img.shields.io/badge/symfony-5.4%20%7C%206.x%20%7C%207.x-blue)](composer.json)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n## 🔌 Compatibility\n\nThis is an **Agent Skill** following the [open standard](https://agentskills.io) originally developed by Anthropic and released for cross-platform use.\n\n**Supported Platforms:**\n- ✅ Claude Code (Anthropic)\n- ✅ Cursor\n- ✅ GitHub Copilot\n- ✅ Other skills-compatible AI agents\n\n\u003e Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.\n\n\n## Features\n\n- **Automatic Discovery**: Finds all packages with type `ai-agent-skill`\n- **AGENTS.md Generation**: Creates XML skill index compatible with [openskills](https://github.com/numman-ali/openskills)\n- **CLI Commands**: `composer list-skills` and `composer read-skill` for skill inspection\n- **Convention Over Configuration**: Works out of the box with zero configuration\n- **Progressive Disclosure**: Lightweight index, full details on demand\n- **Security First**: Rejects absolute paths, validates all skill metadata\n- **Multiple Skills Per Package**: Support for both single and multi-skill packages\n\n## Installation\n\n```bash\ncomposer require netresearch/composer-agent-skill-plugin\n```\n\nDuring installation, Composer will prompt you to authorize the plugin:\n\n```\nnetresearch/composer-agent-skill-plugin contains a Composer plugin which is currently not in your allow-plugins config.\nDo you trust \"netresearch/composer-agent-skill-plugin\" to execute code and wish to enable it now? [y,n,d,?]\n```\n\nChoose `y` to allow the plugin to activate.\n\n### Non-Interactive Installation\n\nFor CI/CD or non-interactive environments, pre-authorize the plugin in your `composer.json`:\n\n```json\n{\n    \"config\": {\n        \"allow-plugins\": {\n            \"netresearch/composer-agent-skill-plugin\": true\n        }\n    }\n}\n```\n\n## Quick Start\n\n### 1. Install Skill Packages\n\nInstall any package with type `ai-agent-skill`:\n\n```bash\ncomposer require vendor/database-analyzer-skill\n```\n\n### 2. Skills Auto-Register\n\nThe plugin automatically:\n- Discovers skill packages during `composer install` or `composer update`\n- Generates/updates `AGENTS.md` in your project root\n- Registers skills in XML format for AI agent consumption\n\n### 3. Use Skills\n\nAI agents automatically discover skills via `AGENTS.md`:\n\n```bash\n# List all available skills\ncomposer list-skills\n\n# Read a specific skill\ncomposer read-skill database-analyzer\n```\n\n## Usage\n\n### List Available Skills\n\n```bash\n$ composer list-skills\n\nAvailable AI Agent Skills:\n\n  database-analyzer        vendor/db-skill               1.2.0\n  oro-bundle-helper        vendor/oro-skill              1.0.0\n  symfony-security         vendor/symfony-security       2.1.0\n\n3 skills available. Use 'composer read-skill \u003cname\u003e' for details.\n```\n\n### Read Skill Details\n\n```bash\n$ composer read-skill database-analyzer\n\nReading: database-analyzer\nPackage: vendor/db-skill v1.2.0\nBase Directory: vendor/vendor/db-skill\n\n---\nname: database-analyzer\ndescription: Analyze and optimize database schemas and relationships\n---\n\n# Database Analyzer Skill\n\n[Full SKILL.md content with instructions and examples]\n\nSkill read: database-analyzer\n```\n\nThe **Base Directory** is the directory containing SKILL.md, used as the root for resolving bundled resources like `references/`, `scripts/`, and `assets/`.\n\n## Creating Skill Packages\n\n### Basic Skill Package\n\n**1. Create composer.json:**\n\n```json\n{\n  \"name\": \"vendor/my-skill\",\n  \"description\": \"My awesome AI agent skill\",\n  \"type\": \"ai-agent-skill\",\n  \"license\": \"MIT\",\n  \"require\": {\n    \"php\": \"^8.2\"\n  }\n}\n```\n\n**2. Create SKILL.md in package root:**\n\n```markdown\n---\nname: my-skill\ndescription: Brief description of what this skill does and when to use it\n---\n\n# My Skill\n\n## Instructions\n\nStep-by-step guidance for using this skill...\n\n## Examples\n\nExample 1: How to use feature X\nExample 2: How to handle scenario Y\n\n## Requirements\n\n- PHP 8.2+\n- Any other dependencies\n```\n\n**3. Publish to Packagist:**\n\n```bash\ngit tag 1.0.0\ngit push --tags\n```\n\n### Multi-Skill Package\n\nFor packages containing multiple skills, configure paths in `extra.ai-agent-skill`:\n\n```json\n{\n  \"name\": \"vendor/database-tools\",\n  \"type\": \"ai-agent-skill\",\n  \"require\": {\n    \"netresearch/composer-agent-skill-plugin\": \"*\"\n  },\n  \"extra\": {\n    \"ai-agent-skill\": [\n      \"skills/analyzer/SKILL.md\",\n      \"skills/optimizer/SKILL.md\",\n      \"skills/validator/SKILL.md\"\n    ]\n  }\n}\n```\n\n### Custom Skill Path\n\nFor a single skill in a non-standard location:\n\n```json\n{\n  \"name\": \"vendor/custom-skill\",\n  \"type\": \"ai-agent-skill\",\n  \"require\": {\n    \"netresearch/composer-agent-skill-plugin\": \"*\"\n  },\n  \"extra\": {\n    \"ai-agent-skill\": \"docs/agent-skill.md\"\n  }\n}\n```\n\n**Security Note:** Only relative paths from package root are allowed. Absolute paths are rejected.\n\n## SKILL.md Schema\n\nSkills must follow the [Claude Code SKILL.md specification](https://code.claude.com/docs/en/skills#write-skill-md):\n\n### Required Frontmatter\n\n```yaml\n---\nname: skill-name          # lowercase, numbers, hyphens only (max 64 chars)\ndescription: Clear description of functionality and triggers (max 1024 chars)\n---\n```\n\n### Optional Frontmatter\n\n```yaml\n---\nname: my-skill\ndescription: What it does and when to use it\nallowed-tools: [Read, Grep, Glob]  # Claude Code only\n---\n```\n\n### Validation Rules\n\n- **Name format**: `^[a-z0-9-]{1,64}$` (lowercase alphanumeric and hyphens)\n- **Name length**: Maximum 64 characters\n- **Description length**: Maximum 1024 characters\n- **YAML syntax**: Valid YAML with proper delimiters (`---`)\n\n## Configuration Options\n\n### Default (Convention)\n\nNo configuration needed. Plugin looks for `SKILL.md` in package root:\n\n```\nvendor/my-skill/\n├── composer.json\n├── SKILL.md          ← Auto-discovered\n└── src/\n```\n\n### Custom Single Skill\n\n```json\n{\n  \"extra\": {\n    \"ai-agent-skill\": \"custom/path/skill.md\"\n  }\n}\n```\n\n### Multiple Skills\n\n```json\n{\n  \"extra\": {\n    \"ai-agent-skill\": [\n      \"skills/skill-one.md\",\n      \"skills/skill-two.md\",\n      \"docs/skill-three.md\"\n    ]\n  }\n}\n```\n\n## Troubleshooting\n\n### No Skills Found\n\n```\n[WARNING] No AI agent skills found in installed packages.\n```\n\n**Solution**: Install packages with `\"type\": \"ai-agent-skill\"` in their composer.json.\n\n### Duplicate Skill Names\n\n```\n[vendor/tools-b] Duplicate skill name 'database-analyzer' (already defined by vendor/tools-a).\n                 Using skill from vendor/tools-b (last one wins).\n```\n\n**Behavior**: Last package wins. Consider renaming skills to avoid conflicts.\n\n### Invalid Frontmatter\n\n```\n[vendor/broken-skill] Invalid frontmatter in 'SKILL.md': Missing required field: 'description'\n```\n\n**Solution**: Ensure SKILL.md has both `name` and `description` fields in valid YAML format.\n\n### Malformed YAML\n\n```\n[vendor/broken-yaml] Malformed YAML in 'SKILL.md':\n                     A colon cannot be used in an unquoted mapping value at line 3\n```\n\n**Solution**: Fix YAML syntax. Use spaces (not tabs), quote values with colons.\n\n### Missing SKILL.md\n\n```\n[vendor/missing-skill] SKILL.md not found at 'SKILL.md'.\n                       Expected SKILL.md in package root (convention).\n```\n\n**Solution**: Create SKILL.md in package root or configure `extra.ai-agent-skill` path.\n\n### Absolute Path Rejected\n\n```\n[vendor/unsafe-config] Absolute paths not allowed in 'extra.ai-agent-skill'.\n                       Use relative paths from package root.\n```\n\n**Solution**: Use relative paths like `\"skills/analyzer.md\"` instead of `/absolute/path`.\n\n## How It Works\n\n### Discovery Process\n\n1. Plugin hooks into `composer install` and `composer update` events\n2. Finds all packages with type `ai-agent-skill`\n3. Reads each package's `composer.json` for skill paths\n4. Parses SKILL.md files and validates frontmatter\n5. Generates XML skill registry in `AGENTS.md`\n\n### AGENTS.md Structure\n\n```xml\n\u003cskills_system priority=\"1\"\u003e\n\n## Available Skills\n\n\u003c!-- SKILLS_TABLE_START --\u003e\n\u003cusage\u003e\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n\nHow to use skills:\n- Invoke: Bash(\"composer read-skill \u003cskill-name\u003e\")\n- The skill content will load with detailed instructions\n- Base directory provided in output for resolving bundled resources\n\u003c/usage\u003e\n\n\u003cavailable_skills\u003e\n\n\u003cskill\u003e\n\u003cname\u003edatabase-analyzer\u003c/name\u003e\n\u003cdescription\u003eAnalyze and optimize database schemas\u003c/description\u003e\n\u003clocation\u003evendor/vendor/db-skill\u003c/location\u003e\n\u003c/skill\u003e\n\n\u003c/available_skills\u003e\n\u003c!-- SKILLS_TABLE_END --\u003e\n\n\u003c/skills_system\u003e\n```\n\n### Progressive Disclosure\n\n- **AGENTS.md**: Lightweight index with skill names and descriptions\n- **read-skill**: Full SKILL.md content loaded on demand\n- **Benefits**: Fast discovery, reduced context size, on-demand details\n\n## Requirements\n\n- PHP 8.2 or higher\n- Composer 2.1 or higher\n- Symfony YAML Component 5.4+, 6.0+, or 7.0+\n- Symfony Console Component 5.4+, 6.0+, or 7.0+\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\n./vendor/bin/phpunit\n\n# Run with coverage\n./vendor/bin/phpunit --coverage-text\n\n# Run specific test\n./vendor/bin/phpunit tests/Unit/SkillDiscoveryTest.php\n```\n\n### Code Quality\n\n```bash\n# PHPStan static analysis (level 8)\n./vendor/bin/phpstan analyse\n\n# PHP CS Fixer (PSR-12)\n./vendor/bin/php-cs-fixer fix --allow-risky=yes\n\n# Check without fixing\n./vendor/bin/php-cs-fixer fix --dry-run --allow-risky=yes\n```\n\n### Project Structure\n\n```\nsrc/\n├── Commands/\n│   ├── ListSkillsCommand.php    # composer list-skills\n│   └── ReadSkillCommand.php     # composer read-skill\n├── Exceptions/\n│   └── InvalidSkillException.php\n├── AgentsMdGenerator.php         # AGENTS.md generation\n├── CommandCapability.php         # Command registration\n├── SkillDiscovery.php            # Package discovery\n└── SkillPlugin.php               # Main plugin class\n\ntests/\n├── Unit/                         # Unit tests\n├── Integration/                  # Integration tests\n└── Fixtures/                     # Test fixtures\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for your changes\n4. Ensure all tests pass (`./vendor/bin/phpunit`)\n5. Run static analysis (`./vendor/bin/phpstan analyse`)\n6. Fix code style (`./vendor/bin/php-cs-fixer fix --allow-risky=yes`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n### Code Standards\n\n- PSR-12 coding style\n- PHPStan level 8\n- 100% type coverage\n- Comprehensive tests (\u003e80% coverage)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Inspiration\n\nInspired by [openskills](https://github.com/numman-ali/openskills) - Universal AI Agent Skills for standardized skill distribution across development environments.\n\n## Links\n\n- [Composer Plugin Documentation](https://getcomposer.org/doc/articles/plugins.md)\n- [Claude Code - SKILL.md Schema](https://code.claude.com/docs/en/skills#write-skill-md)\n- [openskills Project](https://github.com/numman-ali/openskills)\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/netresearch/composer-agent-skill-plugin/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/netresearch/composer-agent-skill-plugin/discussions)\n\n---\n\n**Made with ❤️ by Netresearch**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fcomposer-agent-skill-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetresearch%2Fcomposer-agent-skill-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fcomposer-agent-skill-plugin/lists"}