Agent Skills Standard 🚀

The open standard for High-Density AI coding instructions. Make your AI smarter, faster, and more consistent.

Agent Skills Standard is a modular framework to distribute, sync, and version-control engineering standards across all major AI agents (Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini, Antigravity, and custom LLM workflows).

---

💡 What is this?

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.

---

⚡ The Problem: "The Context Wall"

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.

🛠 The Solution: Digital DNA for AI

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.

---

✨ Features

• 🛡️ 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 (e.g., Flutter + BLoC + Clean Architecture).
• 🔄 Dynamic Re-detection: Automatically re-enables excluded skills if matching dependencies (like Retrofit, Room, or Navigation) are added to your project.
• 🔒 Secure Overrides: Lock specific files in your project so they never get overwritten by the central registry.
• 📊 Semantic Tagging: Skills are tagged with triggers that tell the AI exactly when to apply them.

---

� Token Economy & Optimization

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:

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.

---

🔒 Privacy & Feedback

Feedback Reporter Skill

By default, the CLI syncs a common/feedback-reporter skill that enables you to report when AI makes mistakes or when skill guidance needs improvement. This helps us improve skills for everyone.

What Gets Shared (Only if You Report):

• Skill category and name
• Issue description (written by you or generated by AI)
• Skill Instruction: Exact quote from the skill that was violated
• Actual Action: What the AI did instead
• Decision Reason: Why the AI chose that approach
• Optional context (framework version, scenario)
• Optional AI Model name
• NO code, NO project details, NO personal information

How to Opt-Out: Add to .skillsrc:

skills:
  common:
    exclude: ['feedback-reporter']

Manual Feedback

If you notice a skill needs improvement, you can manually send feedback using (no installation required):

npx agent-skills-standard feedback

How it works:

• Cross-Platform: Works instantly on Windows, MacOS, and Linux via npx.
• The CLI attempts to submit your feedback automatically via our High-Density Feedback Backend (hosted on Render.com).
• No token needed: We handle the GitHub integration securely on the server.

Or via structured comments in your code:

// @agent-skills-feedback
// Skill: react/hooks
// Issue: AI suggested unsafe pattern
// Suggestion: Add guidance for this case

Privacy First: We never collect usage telemetry or analytics. Feedback is only shared if you explicitly trigger it.

---

�🚀 Quick Start (Get running in 60s)

Consume engineering standards in your project instantly.

1. Run the CLI

npx agent-skills-standard@latest init

The interactive wizard will detect your stack and setup your .skillsrc.

2. Sync Standards

npx agent-skills-standard@latest sync

What happened?

1. Dynamic Re-detection: The CLI scans your project dependencies (e.g., build.gradle, pubspec.yaml, package.json). If you've recently added a library that matches an excluded skill, the CLI will automatically re-enable it and update your .skillsrc.
2. Distribution: The CLI fetched the latest High-Density Skills and distributed them into your hidden agent folders (e.g., .cursor/skills/, .github/skills/). Your AI is now "upgraded" with your team's standards.

3. Validate Skills (For Contributors)

npx agent-skills-standard@