Discover and install AI agent skills from Composer dependencies. This library provides a mechanism for PHP packages to distribute AI agent skills (prompts, instructions, templates) that can be automatically discovered and synced into your project.

Key features:

• Automatic skill discovery from installed Composer packages
• Sync skills to your project with a single command
• Override protection to preserve local modifications
• Custom target directory support
• Post-update hook for automatic syncing

your/library
  ├── .claude
  │   └── skills
  │       ├── commit
  │       │   └── SKILL.md
  │       └── review
  │           └── SKILL.md
  └── composer.json

This library requires PHP 8.2 or higher.

composer require agents/skills

1. Install the package via Composer
2. Configure automatic syncing in your composer.json:

{
  "require": {
    "php": ">=8.2"
  },
  "require-dev": {
    "agents/skills": "^0.1.0"
  },
  "scripts": {
    "post-update-cmd": [
      "@composer agents:skills --override"
    ]
  },
  "config": {
    "allow-plugins": {
      "agents/skills": true
    }
  }
}

3. Run composer update to automatically sync skills, or use the commands manually via composer skills.

composer agents:skills [options]

composer agents:skills              # Syncs all skills (default)
composer agents:skills -s commit -o # Sync specific skill with override

Package authors can distribute skills by adding configuration to their composer.json. Both skills and agentskills keys are supported (with skills taking precedence).

your-package/
├── composer.json
└── .claude/
    └── skills/
        ├── commit/
        │   └── SKILL.md
        └── review/
            └── SKILL.md

The simplest way to distribute skills. Each subfolder in the source directory becomes a skill, and all files within are included.

{
    "extra": {
        "skills": {
            "discovery": {
                "source": [".claude/skills"]
            }
        }
    }
}

Features:

• Each folder name becomes the skill name
• All files in each folder are included (non-recursive)
• Hidden files/folders (starting with .) are skipped
• Supports multiple source directories as an array
• Also supports a single string: "source": ".claude/skills"

For fine-grained control over file mappings and output paths.

{
    "extra": {
        "skills": {
            "skills": [
                {
                    "name": "commit",
                    "description": "Git commit helper",
                    "source": ".claude/skills/commit",
                    "files": [
                        {"input": "SKILL.md", "output": "commit/SKILL.md"}
                    ]
                }
            ]
        }
    }
}

Combine discovery with explicit overrides. Explicit skills take precedence over discovered ones.

{
    "extra": {
        "skills": {
            "discovery": {
                "source": [".claude/skills"]
            },
            "skills": [
                {
                    "name": "commit",
                    "description": "Custom commit description",
                    "source": ".claude/skills/commit",
                    "files": [
                        {"input": "SKILL.md", "output": ".claude/custom/commit.md"}
                    ]
                }
            ]
        }
    }
}

See the playground for a complete example of skills in action.