README

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

Installation

This library requires PHP 8.2 or higher.

composer require agents/skills

Quick Start

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
    }
  }
}

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

Console

composer agents:skills [options]

Examples

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

Custom Skill

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

Skill Structure

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

Discovery Mode (Recommended)

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"

Explicit Mode

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"}
                    ]
                }
            ]
        }
    }
}

Mixed Mode

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"}
                    ]
                }
            ]
        }
    }
}

Configuration Reference

Example

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