Skills to Plugins (`skills-to-plugins`)

This skill provides an expert workflow for migrating legacy flat skills repositories into Agent Plugins v1.0.0 Specification packages, authoring new plugins from scratch, and linting plugins for ongoing spec conformance.

Canonical Specifications

• Agent Plugins Specification: agentplugins/agent-plugins-spec (Normative Text: spec/1.0.0.md)
• Agent Skills Specification: agentskills.io/specification.md
• Reference Summary: See references/spec-summary.md for a condensed lookup table of normative rules and schema boundaries.

Reference & Asset Files (Progressive Disclosure)

• references/spec-summary.md — Normative reference for Agent Plugins v1.0.0 and Agent Skills spec constraints.
• references/discovery-compatibility.md — Detailed analysis of npx skills, gemini skills, and agy discovery algorithms and .claude-plugin/marketplace.json indexing.
• references/migration-playbook.md — Step-by-step phased migration guide (Phases 0 through 5).
• references/conformance-debt-catalog.md — Symptom and resolution lookup for common skills frontmatter and path anti-patterns.
• scripts/audit-conformance.sh — Read-only debt auditor that scans a repository for frontmatter issues, oversized descriptions, non-executable scripts, and parent-relative link dependencies.
• scripts/validate-plugins.sh — Spec validator enforcing $schema URLs, name↔directory matches, description limits ($\le 1024$), script executable bits, and marketplace JSON syntax.
• assets/plugin.json.template — Template for plugin.json package manifest.
• assets/mcp.json.template — Template for mcp.json server definitions.
• assets/marketplace.json.template — Template for .claude-plugin/marketplace.json.

Modes

Mode 1: Audit an Existing Repository (Read-Only)

Execute a comprehensive, non-destructive audit of an existing skills repository before planning a migration.

1. Run the audit script from the repository root:

   scripts/audit-conformance.sh

2. Read references/conformance-debt-catalog.md to classify every detected debt item (missing frontmatter, oversized descriptions, non-executable scripts, un-nested top-level version: fields).
3. Analyze parent-relative links (e.g. ../sibling/SKILL.md) to identify co-dependent orchestrator and sub-skills that belong in the same plugin bundle.
4. Present an Audit & Grouping Proposal table to the user listing:
   • Conformance debt items to resolve.
   • Proposed thematic plugin groupings (plugins/<plugin-name>/skills/<skill-name>).
   • Confirmation prompt before proceeding to Mode 2.

Mode 2: Migrate Repository to Agent Plugins v1.0.0

Prerequisite: Mode 1 audit completed and user approved the grouping proposal.

Execute the migration in strict phase order as detailed in references/migration-playbook.md:

1. Phase 0 (Hygiene): Add untracked machine-local tooling directories to .gitignore and confirm no symlinks escape the repository root.
2. Phase 1 (Conformance Debt): Resolve all frontmatter issues, truncate descriptions > 1024 characters, move version: under metadata:, add license: Apache-2.0, chmod +x scripts, and move static assets from references/ to assets/.
3. Phase 2 (Directory Restructure): Execute directory moves into plugins/<plugin>/skills/<skill> using git mv to preserve commit history.
4. Phase 3 (Manifests): Generate plugins/<plugin>/plugin.json for each plugin and .claude-plugin/marketplace.json at root using templates in assets/.
5. Phase 4 (Validation): Run scripts/validate-plugins.sh and verify 0 errors.

Mode 3: Author a New Plugin

Create a new conformant plugin package inside an existing or new repository.

1. Choose a spec-valid plugin name (^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$).
2. Create directory structure plugins/<plugin-name>/skills/<skill-name>/.
3. Copy assets/plugin.json.template to plugins/<plugin-name>/plugin.json and fill in $schema, name, version, and metadata.
4. Create plugins/<plugin-name>/skills/<skill-name>/SKILL.md with valid frontmatter (name, description $\le 1024$, license).
5. Update .claude-plugin/marketplace.json to include the new plugin and skill paths.
6. Validate with scripts/validate-plugins.sh.

Mode 4: Lint Ongoing Conformance

Verify ongoing spec compliance for CI/CD or local pre-commit checks.

1. Run scripts/validate-plugins.sh locally or in GitHub Actions (.github/workflows/validate.yml).
2. Fix any flagged issues: schema URL mismatches, frontmatter description overruns (> 1024 chars), or un-indexed marketplace entries.

Guiding Principles

1. Strict Containment (§4.1): Symlinks or relative paths escaping the plugin root violate spec §4.1 containment. Never create symlink farms pointing outside a plugin.
2. Cross-Skill Coupling Detection: Parent-relative links (../) inside SKILL.md indicate co-dependent skills that MUST be packaged together inside the same plugin root so links resolve legally.
3. Phase Ordering: Always resolve frontmatter and license debt before running git mv so history records clean directory renames without noisy content diffs.
4. Canonical Spec Verification: Always verify specification questions against canonical sources (agentplugins/agent-plugins-spec and agentskills.io/specification.md) rather than relying solely on local summary distillations.