next-upgrade

Think of Agent Skills Standard as a universal instruction manual for your AI assistant.

Usually, when you use AI for work, you have to constantly remind it of your "house rules" (e.g., _"Make sure to handle errors this way"_ or _"Use this specific layout"_). This project allows teams to package those rules into "Skills" that you can plug into any AI tool instantly.

Why does this matter?

• For Managers: Ensure your entire team writes high-quality code that follows your company's standards, regardless of which AI tool they use.
• For Non-IT Users: You don't need to know _how_ the rules are written; you just run one command to "upgrade" your AI with professional-grade engineering knowledge.
• For Teams: No more "Hey, why did the AI write it this way?"—everyone’s AI uses the same playbook.

---

Modern AI coding agents are powerful, but they struggle when managing project-wide rules:

1. Information Overload: Providing too many instructions at once confuses the AI and makes it forgetful.
2. Version Chaos: Every team member has a different version of "best practices" floating around their local computer.
3. Wasted Space: Long, wordy instructions "eat up" the AI's limited memory (the Context Window), making it more expensive and less effective.

Agent Skills Standard treats instructions as versioned dependencies, much like software libraries.

• 🎯 Smart Loading: We use a "Search-on-Demand" pattern. The AI only looks at detailed examples when it specifically needs them, saving its memory for your actual code.
• 🚀 High-Density Language: We use a specialized "Compressed Syntax" that is 40% more efficient than normal English. This means the AI understands more while using fewer resources.
• 🔁 One-Click Sync: A single command ensures your AI tool stays up-to-date with your team's latest standards.

---

• 🛡️ Multi-Agent Support: Out-of-the-box mapping for Cursor, Claude Dev, GitHub Copilot, and more.
• 📦 Modular Registry: Don't load everything. Only enable the skills your project actually uses.
• ⚡ Proactive Activation (Universal): Generates a compressed index in AGENTS.md for 100% activation reliability across Cursor, Windsurf, Claude Code, and more.
• 🔄 Dynamic Re-detection: Automatically re-enables skills if matching dependencies are added.
• 🔒 Secure Overrides: Lock specific files so they never get overwritten.
• 📊 Semantic Tagging: Skills tagged with triggers for exact application.

---

• init: Initialize a fresh .skillsrc config.
• sync: Sync skills from remote registry and automatically update the AGENTS.md index.
• validate: Validate skill format and token standards.
• feedback: Report skill violations or improvements.
• upgrade: Upgrade the CLI to the latest version.

---

To ensure AI efficiency, this project follows a strict Token Economy. Every skill is audited for its footprint in the AI's context window.

📏 Our Standards

• High-Density: Core rules in SKILL.md are kept under 70 lines.
• Efficiency: Target < 500 tokens per primary skill file.
• Progressive Disclosure: Heavy examples, checklists, and implementation guides are moved to the references/ directory and are only loaded by the agent when specific context matches.

🛠️ Token Calculation

We provide a built-in tool in the CLI to estimate and track the token footprint:

```bash

pnpm calculate-tokens

```

This command:

1. Scans all SKILL.md files in the registry.
2. Calculates character-based token estimates.
3. Updates skills/metadata.json with category metrics (total tokens, avg/skill, and identifying the largest skills).

By maintaining a "Lean Registry," we ensure that your AI assistant remains fast and focused, preserving the majority of its context window for your actual project code.

---

Feedback Reporter Skill

By default, the CLI syncs a common/feedback-reporter skill that enables you to report when AI makes mistakes or when skil