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

Install the package via Composer
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
    }
  }
}

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

Console

composer agents:skills [options]

Option	Short	Description
`--skill`	`-s`	Sync only the specified skill by name
`--override`	`-o`	Override existing files instead of skipping them
`--target`	`-t`	Target directory for skills (default: `.claude/skills`)

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

Field	Required	Description
`discovery.source`	No	Array of directories to scan for folder-based skills
`skills`	No	Array of explicit skill definitions
`skills[].name`	Yes	Unique identifier for the skill
`skills[].description`	No	Human-readable description
`skills[].source`	Yes	Path to skill files relative to package root
`skills[].files`	Yes	Array of file mappings
`skills[].files[].input`	Yes	Source file path relative to `source`
`skills[].files[].output`	Yes	Destination path relative to target directory

Example

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

agents / skills

Maintainers

Details