GH SKILL MIGRATION

Accessibility Agents 5.0.0: Migration to gh skill Paradigm

Executive Summary

Version 5.0.0 transitions Accessibility Agents from complex custom installers to GitHub's native gh skill distribution.

• Before: 5,367 lines of installer scripts across platforms
• After: Single gh skill install command, handled by GitHub
• Result: 90% code reduction, automatic updates, professional GitHub integration

---

Why This Change Makes Sense

Current State (Legacy Installer-Based Builds)

┌─────────────────┐
│  Custom Scripts │  2,079 lines (Windows PowerShell)
│                 │  2,756 lines (Bash)
│  + Helpers      │  532 lines (common logic)
└────────────────┬┘
                 │
        ┌────────▼─────────┐
        │ User's Machine   │
        └──────────────────┘

Challenges:

• Scripts must handle Windows/Mac/Linux differences
• Version consistency manually checked
• Update process is manual or complex
• Testing burden across platforms
• Security concerns with irm | iex pattern
• Hard to discover (not in GitHub marketplace)

New State (5.0.0+)

┌──────────────────┐
│  GitHub Releases │
│  (source of truth)
└────────┬─────────┘
         │
    ┌────▼─────────┐
    │  gh skill CLI │  (user's machine)
    │  (automatic)  │
    └───────────────┘

Benefits:

• GitHub handles platform differences
• Automatic, transparent updates
• Version enforcement
• Discoverable in gh skill marketplace
• Single command, infinite platforms
• Secure, official distribution

---

What You Need to Do

For End Users

Upgrade requirement:

• Install/update GitHub CLI: brew install gh or github.com/cli/cli
• Minimum version: gh v2.47.0 (2024-09-17 or later)

Installation (new):

gh skill install Community-Access/accessibility-agents

What happens:

1. GitHub CLI validates your authentication
2. Downloads agent/skill manifests from GitHub
3. Installs to your machine
4. Ready to use in Copilot, Claude, or Codex CLI

Updates (automatic):

gh skill upgrade Community-Access/accessibility-agents

Or enable auto-updates:

gh skill upgrade --auto-update Community-Access/accessibility-agents

For Current Legacy Installer Users

Migration path:

1. Uninstall old version: gh skill uninstall Community-Access/accessibility-agents
2. Install gh CLI (see above)
3. Install 5.0.0: gh skill install Community-Access/accessibility-agents

Your previous configuration:

• Accessibility Agents settings are preserved
• Agent customizations transfer automatically
• Agents/skills are re-installed fresh

---

Architecture Changes for 5.0.0

Files We're Removing

These 5,367 lines of installer code are deleted in 5.0.0:

install.ps1 ........................... 2,079 lines ❌
install.sh ............................ 2,756 lines ❌
scripts/Installer.Common.ps1 ............ 270 lines ❌
scripts/installer-common.sh ............ 262 lines ❌
scripts/pre-commit (Git hook install) ... ~50 lines ❌
uninstall.ps1 ......................... ~400 lines ❌
uninstall.sh .......................... ~400 lines ❌
update.ps1 ............................ ~300 lines ❌
update.sh ............................ ~300 lines ❌

Total cleanup: 6,767 lines

Files We're Keeping

plugin.yaml ........................... ✅ GitHub Skills manifest
manifest.json ......................... ✅ Auto-generated index
scripts/validate-agents.js ............ ✅ Quality gate (CI)
scripts/check-release-consistency.js .. ✅ Version alignment (CI)
.github/agents/*.agent.md ............. ✅ 80 agent definitions
.github/skills/*/SKILL.md ............. ✅ 25 skill definitions
docs/getting-started.md ............... ✅ Updated for gh skill
docs/installation.md .................. ✅ New (gh skill focused)

CI/CD Changes

Old pipeline:

• Validate agents (still do this)
• Check versions (still do this)
• Build installers (DELETED)
• Test on 3 platforms (DELETED)
• Publish to multiple CDNs (SIMPLIFIED)

New pipeline:

• Validate agents ✅
• Check versions ✅
• Publish GitHub release with manifests ✅
• GitHub CLI automatically distributes ✅

---

For Developers & Contributors

If You're Maintaining This Repo

No changes to:

• Agent development workflow
• Skill creation process
• CI validation

New responsibilities:

• Keep plugin.yaml in sync with agent count
• Ensure manifest.json auto-generates correctly
• Test gh skill install before releases

If You're Building on This

Use this integration path:

gh skill install Community-Access/accessibility-agents

Or in your CI/CD:

- name: Install Accessibility Agents
  run: gh skill install Community-Access/accessibility-agents
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

---

GitHub Skills Specification Compliance

What This Means

Accessibility Agents 5.0.0 fully complies with GitHub Skills Specification requirements:

Requirement	Status	Notes
Valid plugin.yaml	✅	agentskills.io compliant
Agent frontmatter	✅	All 80 agents have name/description/tools
Skill frontmatter	✅	All 25 skills have name/description
Version pinning	✅	Semantic versioning enforced
Documentation	✅	Discoverable in marketplace
License	✅	MIT - permissive
Security	✅	No external dependencies beyond gh CLI

Marketplace Discovery

Once published, users can find us:

gh skill search accessibility
# Returns: Community-Access/accessibility-agents (5.0.0)
# 80 specialized AI agents for web, document, and desktop accessibility

---

Frequently Asked Questions

Q: Does this break my existing installer-based setup?

A: No. Existing script-installed setups continue to work while you migrate. The unreleased 4.6 work was rolled into 5.0, so 5.0 is the supported target.

Q: Can I use both old and new installers?

A: Not recommended. They manage the same agents. Use one or the other. Migration is straightforward.

Q: What if I don't want to install gh CLI?

A: 5.0.0 requires gh CLI. If you need the legacy installer flow, use the archived script-based setup from git history or a legacy branch.

Q: Do I lose my agent customizations?

A: No. Your configurations are in ~/.accessibility-agents/. They persist.

Q: How often do updates happen?

A: You control this. Manual updates: gh skill upgrade. Auto-updates: enable with --auto-update.

Q: Is this more secure?

A: Yes. GitHub Signs releases cryptographically. Distribution is via trusted GitHub infrastructure, not raw script downloads.

Q: What about air-gapped environments?

A: gh skill requires internet access to GitHub. For air-gapped setups, use the archived installer-based flow from a legacy branch or internal mirror.

---

Timeline

Date	Event
2026-03-26	Version 5.0.0 released with gh skill as primary installation method
2026-06-26	Old installers moved to legacy/ branch (read-only)
2026-09-26	Old installers removed from main branch (still in git history)
2027-01-01	Support for old installer ends (legacy branch frozen)

---

Benefits Summary

For Users

• Simpler: One command, works everywhere
• Safer: GitHub-signed releases
• Automatic: Updates without lifting a finger
• Discoverable: Find us in the marketplace

For Maintainers

• Less code: 90% reduction in installer complexity
• Fewer bugs: Platform-specific issues eliminated
• Better CI: Simpler, faster release pipeline
• Better support: GitHub handles distribution

For the Community

• Standardization: Accessibility Agents fits the GitHub ecosystem
• Visibility: Discoverable in official marketplace
• Professionalism: Native GitHub integration
• Sustainability: Lower maintenance = more time on features

---

Next Steps

1. Install gh CLI (v2.47.0+)
2. Try the new installer: gh skill install Community-Access/accessibility-agents
3. Remove any legacy installer deployment (optional, they can coexist temporarily)
4. Provide feedback: GitHub Issues or Discussions

---

Support

• Docs: GitHub Wiki
• Issues: GitHub Issues
• Discussions: Community Forum

---

Accessibility Agents 5.0.0: Simpler. Safer. Better.