agent-skills-standard 1.9.3 → 1.10.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -225
- package/dist/index.js +113 -56
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,21 +3,6 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/agent-skills-standard)
|
|
4
4
|
[](https://github.com/HoangNguyen0403/agent-skills-standard/blob/main/LICENSE)
|
|
5
5
|
|
|
6
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/nestjs-v1.2.1)
|
|
7
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/nextjs-v1.2.0)
|
|
8
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/golang-v1.1.0)
|
|
9
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/angular-v1.2.0)
|
|
10
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/kotlin-v1.1.0)
|
|
11
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/java-v1.1.0)
|
|
12
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/spring-boot-v1.1.0)
|
|
13
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/android-v1.1.0)
|
|
14
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/swift-v1.1.0)
|
|
15
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/ios-v1.2.0)
|
|
16
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/php-v1.1.0)
|
|
17
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/laravel-v1.1.0)
|
|
18
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/database-v1.1.1)
|
|
19
|
-
[](https://github.com/HoangNguyen0403/agent-skills-standard/releases/tag/quality-engineering-v1.1.0)
|
|
20
|
-
|
|
21
6
|
**The heavy-lifting engine for High-Density AI Agent Instructions. Deploy professional standards to any project in seconds.**
|
|
22
7
|
|
|
23
8
|
The `agent-skills-standard` CLI is the official command-line tool to manage, sync, and version-control engineering standards (often called **"Cursor Rules"** or **"Agent Skills"**) across all major AI agents (**Cursor, Claude Code, GitHub Copilot, Gemini, Roo Code, and more**).
|
|
@@ -27,15 +12,11 @@ The `agent-skills-standard` CLI is the official command-line tool to manage, syn
|
|
|
27
12
|
## 📌 Table of Contents
|
|
28
13
|
|
|
29
14
|
- [💡 What does this tool do?](#-what-does-this-tool-do)
|
|
30
|
-
- [🎯 Who is this for?](#-who-is-this-for)
|
|
31
|
-
- [⚡ The Problem: The Context Wall](#-the-problem-the-context-wall)
|
|
32
15
|
- [🛠 The Solution: Digital DNA for AI](#-the-solution-digital-dna-for-ai)
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
- [
|
|
37
|
-
- [🏗 Contributing](#-contributing)
|
|
38
|
-
- [❓ FAQ](#-faq)
|
|
16
|
+
- [🚀 Installation & Quick Start](#-installation--quick-start)
|
|
17
|
+
- [⚙️ Configuration (`.skillsrc`)](#️-configuration-skillsrc)
|
|
18
|
+
- [🔒 Privacy & Security](#-privacy--security)
|
|
19
|
+
- [❓ FAQ & Links](#-faq--links)
|
|
39
20
|
|
|
40
21
|
---
|
|
41
22
|
|
|
@@ -65,171 +46,39 @@ graph LR
|
|
|
65
46
|
|
|
66
47
|
---
|
|
67
48
|
|
|
68
|
-
## ⚡ The Problem: "The Context Wall"
|
|
69
|
-
|
|
70
|
-
Modern AI coding agents are powerful, but they have major flaws:
|
|
71
|
-
|
|
72
|
-
1. **Memory Drain**: Giant rule files consume **30% - 50% of the AI's memory**, making it less effective for actual coding.
|
|
73
|
-
2. **Version Chaos**: Team members often have different "best practices," leading to inconsistent code.
|
|
74
|
-
3. **Wordy Prose**: Human-style instructions are token-heavy and often ignored by AI during complex logical tasks.
|
|
75
|
-
|
|
76
|
-
**Agent Skills Standard** solves this by treating prompt instructions as **versioned dependencies**, similar to how you manage software libraries.
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
49
|
## 🛠 The Solution: Digital DNA for AI
|
|
81
50
|
|
|
82
|
-
Agent Skills Standard
|
|
51
|
+
Modern AI coding agents are powerful, but giant rule files consume **30% - 50% of the AI's memory**, making it less effective. Agent Skills Standard solves this by treating prompt instructions as **versioned dependencies**.
|
|
83
52
|
|
|
84
53
|
- **🎯 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.
|
|
85
54
|
- **🚀 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.
|
|
86
55
|
- **🔁 One-Click Sync**: A single command ensures your AI tool stays up-to-date with your team's latest standards.
|
|
87
56
|
|
|
88
|
-
---
|
|
89
|
-
|
|
90
|
-
## 🛡️ Security & Trust
|
|
91
|
-
|
|
92
|
-
We take security seriously. Here is what you need to know about how the CLI works:
|
|
93
|
-
|
|
94
|
-
- **No Hidden Scripts**: The CLI `sync` command only downloads **text files** (Markdown/JSON). It does _not_ download or execute binaries, scripts, or unknown code.
|
|
95
|
-
- **No "Code Injection"**: When we say "injection", we mean **Prompt Injection** (adding context to the AI's conversation history), NOT code injection (running malware).
|
|
96
|
-
- **Transparent Operations**:
|
|
97
|
-
- The CLI fetches a standard directory structure from the [official registry](https://github.com/HoangNguyen0403/agent-skills-standard).
|
|
98
|
-
- It copies these text files to your local `.cursor/skills` or `.agent/skills` folder.
|
|
99
|
-
- It updates `AGENTS.md` (a text file index).
|
|
100
|
-
- **That is it.** No background services, no daemons, no hidden network calls.
|
|
101
|
-
|
|
102
|
-
---
|
|
103
|
-
|
|
104
|
-
## 📊 Efficiency & Benchmark
|
|
105
|
-
|
|
106
|
-
Every skill delivered by this CLI is audited for its footprint in the AI's context window.
|
|
107
|
-
|
|
108
|
-
| Metric | Typical Saving | Status | Version | Avg. Footprint |
|
|
109
|
-
| :----------------- | :-------------- | :----- | :------- | :------------- |
|
|
110
|
-
| **Global Average** | **88% Savings** | 10/10 | `v1.1.0` | ~398 tokens |
|
|
111
|
-
|
|
112
57
|
> [!IMPORTANT]
|
|
113
58
|
> **Context is Currency**: By reducing instruction overhead by **88%**, you free up your AI's memory and budget for complex logic and large codebases.
|
|
114
59
|
|
|
115
|
-
- **🛡️ Multi-Agent Support**: Out-of-the-box mapping for Cursor, Claude Dev, GitHub Copilot, and more.
|
|
116
|
-
- **📦 Modular Registry**: Don't load everything. Only enable the skills your project actually uses.
|
|
117
|
-
- **⚡ Proactive Activation (Universal)**: Generates a compressed index in `AGENTS.md` for 100% activation reliability across Cursor, Windsurf, Claude Code, and more.
|
|
118
|
-
- **🔄 Dynamic Re-detection**: Automatically re-enables skills if matching dependencies are added.
|
|
119
|
-
- **🔒 Secure Overrides**: Lock specific files so they never get overwritten.
|
|
120
|
-
- **📊 Semantic Tagging**: Skills tagged with triggers for exact application.
|
|
121
|
-
- **🤖 Agent Workflows**: Sync executable workflows (.md files) that agents can follow to perform complex tasks.
|
|
122
|
-
|
|
123
60
|
---
|
|
124
61
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| Version | Date | Skills | Avg Tokens | Savings (%) | Report |
|
|
128
|
-
| --- | --- | --- | --- | --- | --- |
|
|
129
|
-
| v1.9.3 | 2026-03-15 | 229 | 460 | 87% | [Report](benchmarks/archive/v1.9.3.md) |
|
|
130
|
-
| v1.9.2 | 2026-03-07 | 228 | 458 | 87% | [Report](benchmarks/archive/v1.9.2.md) |
|
|
131
|
-
| v1.9.1 | 2026-03-07 | 228 | 458 | 87% | [Report](benchmarks/archive/v1.9.1.md) |
|
|
132
|
-
|
|
133
|
-
## � Token Economy & Optimization
|
|
134
|
-
|
|
135
|
-
To ensure AI efficiency, this project follows a strict **Token Economy**. Every skill is audited for its footprint in the AI's context window.
|
|
136
|
-
|
|
137
|
-
### 📏 Our Standards
|
|
138
|
-
|
|
139
|
-
- **High-Density**: Core rules in `SKILL.md` are kept under **100 lines**.
|
|
140
|
-
- **Efficiency**: Target **< 500 tokens** per primary skill file.
|
|
141
|
-
- **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.
|
|
142
|
-
|
|
143
|
-
## 🔒 Privacy & Feedback
|
|
144
|
-
|
|
145
|
-
### Feedback Reporter Skill
|
|
146
|
-
|
|
147
|
-
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.**
|
|
148
|
-
|
|
149
|
-
**What Gets Shared (Only if AI Agent Report):**
|
|
150
|
-
|
|
151
|
-
- Skill category/name
|
|
152
|
-
- Issue description (written by you or generated by AI)
|
|
153
|
-
- **Skill Instruction**: Exact quote from the skill that was violated
|
|
154
|
-
- **Actual Action**: What the AI did instead
|
|
155
|
-
- **Decision Reason**: Why the AI chose that approach
|
|
156
|
-
- Optional context (framework version, scenario)
|
|
157
|
-
- Optional AI Model name
|
|
158
|
-
- **NO code, NO project details, NO personal information**
|
|
159
|
-
|
|
160
|
-
**How to Opt-Out:**
|
|
161
|
-
Add to `.skillsrc`:
|
|
162
|
-
|
|
163
|
-
```yaml
|
|
164
|
-
skills:
|
|
165
|
-
common:
|
|
166
|
-
exclude: ['feedback-reporter']
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
**How to Report Issues:**
|
|
170
|
-
Use structured comments:
|
|
171
|
-
|
|
172
|
-
```typescript
|
|
173
|
-
// @agent-skills-feedback
|
|
174
|
-
// Skill: react/hooks
|
|
175
|
-
// Issue: AI suggested unsafe pattern
|
|
176
|
-
// Suggestion: Add guidance for this case
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
**Privacy First**: We never collect usage telemetry or analytics. Feedback is only shared if you explicitly trigger it.
|
|
180
|
-
|
|
181
|
-
#### Manual Feedback
|
|
182
|
-
|
|
183
|
-
If you notice a skill needs improvement, you can manually send feedback using:
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
ags feedback
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
Or via structured comments in your code:
|
|
190
|
-
|
|
191
|
-
```typescript
|
|
192
|
-
// @agent-skills-feedback
|
|
193
|
-
// Skill: react/hooks
|
|
194
|
-
// Issue: AI suggested unsafe pattern
|
|
195
|
-
// Suggestion: Add guidance for this case
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
## 🚀 Installation
|
|
62
|
+
## 🚀 Installation & Quick Start
|
|
199
63
|
|
|
200
64
|
You can run the tool instantly without installing, or install it globally for convenience:
|
|
201
65
|
|
|
202
66
|
```bash
|
|
203
67
|
# Use instantly (Recommended)
|
|
68
|
+
npx agent-skills-standard@latest init
|
|
204
69
|
npx agent-skills-standard@latest sync
|
|
205
70
|
|
|
206
71
|
# Or install globally
|
|
207
72
|
npm install -g agent-skills-standard
|
|
208
|
-
|
|
209
|
-
# Use the short alias
|
|
210
73
|
ags sync
|
|
211
74
|
```
|
|
212
75
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
## 🛠 Basic Commands
|
|
216
|
-
|
|
217
|
-
### 1. Setup Your Project
|
|
218
|
-
|
|
219
|
-
Run this once to detect your project type and choose which "skills" you want your AI to have.
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
npx agent-skills-standard@latest init
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
### 2. Boost Your AI
|
|
226
|
-
|
|
227
|
-
Run this to fetch the latest high-density instructions and install them into your hidden agent folders (like `.cursor/skills/` or `.github/skills/`).
|
|
228
|
-
|
|
229
|
-
```bash
|
|
230
|
-
npx agent-skills-standard@latest sync
|
|
76
|
+
### 🛠 Basic Commands
|
|
231
77
|
|
|
232
|
-
|
|
78
|
+
- `init`: Detect your project type and choose which "skills" you want your AI to have.
|
|
79
|
+
- `sync`: Fetch the latest high-density instructions and install them into your hidden agent folders (like `.cursor/skills/` or `.github/skills/`).
|
|
80
|
+
- `validate`: Validate custom skills against the standard.
|
|
81
|
+
- `feedback`: Submit feedback to improve the global registry.
|
|
233
82
|
|
|
234
83
|
---
|
|
235
84
|
|
|
@@ -245,90 +94,55 @@ skills:
|
|
|
245
94
|
ref: flutter-v1.1.0
|
|
246
95
|
# 🚫 Exclude specific sub-skills from being synced
|
|
247
96
|
exclude: ['getx-navigation']
|
|
248
|
-
# ➕ Include specific skills (supports cross-category 'category/skill'
|
|
97
|
+
# ➕ Include specific skills (supports cross-category 'category/skill' syntax)
|
|
249
98
|
include:
|
|
250
99
|
- 'bloc-state-management'
|
|
251
100
|
- 'react/hooks'
|
|
252
|
-
- 'common/*'
|
|
253
101
|
# 🔒 Protect local modifications from being overwritten
|
|
254
102
|
custom_overrides: ['bloc-state-management']
|
|
255
103
|
# 🤖 Optional: Sync workflows to .agent/workflows/
|
|
256
104
|
workflows: true
|
|
257
105
|
```
|
|
258
106
|
|
|
259
|
-
### Key Options
|
|
260
|
-
|
|
261
|
-
- **`exclude`**: A list of skill IDs to skip during synchronization.
|
|
262
|
-
- **`include`**: A list of skill IDs to fetch. Supports:
|
|
263
|
-
- **Relative Path**: `bloc-state-management` (from current category)
|
|
264
|
-
- **Absolute Path**: `react/hooks` (pull specific skill from another category)
|
|
265
|
-
- **Glob Path**: `common/*` (pull ALL skills from another category)
|
|
266
|
-
- **`custom_overrides`**: A list of skill IDs that the CLI should **never** overwrite.
|
|
267
|
-
- **`ref`**: Specify a specific version or tag for the skills.
|
|
268
|
-
|
|
269
107
|
---
|
|
270
108
|
|
|
271
|
-
##
|
|
272
|
-
|
|
273
|
-
- **🎯 Efficiency First**: Uses a "Search-on-Demand" pattern that only loads information when the AI needs it, saving its "brain power" for your code.
|
|
274
|
-
- **🚀 High-Density Instructions**: Optimized syntax that is **40% more compact** than standard English.
|
|
275
|
-
- **🛡️ Universal Support**: Works out-of-the-box with Cursor, Claude, GitHub Copilot, and more.
|
|
276
|
-
- **🔒 Secure Protection**: Mark specific files as "Locked" (overrides) so the CLI never changes your custom tweaks.
|
|
277
|
-
- **🧪 Production-Grade Reliability**: Guarded by a 100% statement coverage test suite and strict CI enforcement.
|
|
278
|
-
|
|
279
|
-
### 📂 Browse All Available Skills
|
|
280
|
-
|
|
281
|
-
The Agent Skills Standard is a modular library designed to be the universal language for engineering standards. Browse the categories below to see the key modules and metrics for each stack.
|
|
282
|
-
|
|
283
|
-
| Stack / Category | Key Modules | Typical Saving | Status | Version | Skills | Avg. Footprint |
|
|
284
|
-
| :---------------------- | :-------------------------------------- | :------------- | :------ | :------- | :----- | :------------- |
|
|
285
|
-
| **Common Patterns** | Accessibility, Best Practices, Security | **82%** | Healthy | `v1.7.2` | 25 | ~657 tokens |
|
|
286
|
-
| **Flutter** | BLoC, Riverpod, Clean Architecture | **87%** | Healthy | `v1.4.1` | 21 | ~466 tokens |
|
|
287
|
-
| **Dart** | Language, Tooling | **87%** | Healthy | `v1.1.0` | 3 | ~459 tokens |
|
|
288
|
-
| **TypeScript** | Type Safety, Tooling | **85%** | Healthy | `v1.1.0` | 4 | ~541 tokens |
|
|
289
|
-
| **JavaScript** | Functional Programming, Patterns | **89%** | Healthy | `v1.1.0` | 3 | ~408 tokens |
|
|
290
|
-
| **React** | React 18+, Hooks, Performance | **88%** | Healthy | `v1.1.0` | 8 | ~427 tokens |
|
|
291
|
-
| **React Native** | Architecture, Performance | **87%** | Healthy | `v1.2.0` | 13 | ~469 tokens |
|
|
292
|
-
| **NestJS** | Architecture, Security, BullMQ | **84%** | Healthy | `v1.2.1` | 21 | ~570 tokens |
|
|
293
|
-
| **Next.js** | App Router, SEO, Performance | **86%** | Healthy | `v1.2.0` | 18 | ~506 tokens |
|
|
294
|
-
| **Angular** | Architecture, Signals, RxJS | **92%** | Healthy | `v1.2.0` | 15 | ~307 tokens |
|
|
295
|
-
| **Android** | Compose, Architecture, Networking | **91%** | Healthy | `v1.1.0` | 22 | ~315 tokens |
|
|
296
|
-
| **iOS** | Architecture, SwiftUI, Concurrency | **88%** | Healthy | `v1.2.0` | 15 | ~431 tokens |
|
|
297
|
-
| **Swift** | Concurrency, Architecture | **90%** | Healthy | `v1.1.0` | 8 | ~377 tokens |
|
|
298
|
-
| **Kotlin** | Language, Concurrency | **87%** | Healthy | `v1.1.0` | 4 | ~475 tokens |
|
|
299
|
-
| **Java** | Language, Concurrency | **85%** | Healthy | `v1.1.0` | 5 | ~543 tokens |
|
|
300
|
-
| **Spring Boot** | Architecture, Security | **89%** | Healthy | `v1.1.0` | 10 | ~393 tokens |
|
|
301
|
-
| **Go (Golang)** | Clean Architecture, Security | **89%** | Healthy | `v1.1.0` | 10 | ~398 tokens |
|
|
302
|
-
| **PHP** | Error Handling, PHP 8+ | **91%** | Healthy | `v1.1.0` | 7 | ~340 tokens |
|
|
303
|
-
| **Laravel** | Solid Patterns, Clean Architecture | **90%** | Healthy | `v1.1.0` | 10 | ~383 tokens |
|
|
304
|
-
| **Database** | PostgreSQL, MongoDB, Redis | **80%** | Healthy | `v1.1.1` | 3 | ~720 tokens |
|
|
305
|
-
| **Quality Engineering** | BA, TDD, Zephyr, Automation | **87%** | Healthy | `v1.1.0` | 4 | ~480 tokens |
|
|
306
|
-
|
|
307
|
-
> [!TIP]
|
|
308
|
-
> **View the Complete Registry**: For a full list of all 160+ skills, visit the [Skills Directory](../skills/README.md).
|
|
309
|
-
|
|
310
|
-
> [!TIP]
|
|
311
|
-
> Run `ags benchmark` (coming soon) or check the [root report](../benchmark-report.md) for full scientific methodology.
|
|
109
|
+
## 🔒 Privacy & Security
|
|
312
110
|
|
|
313
|
-
|
|
111
|
+
We take security seriously. Here is what you need to know:
|
|
314
112
|
|
|
315
|
-
|
|
113
|
+
- **No Code Execution**: The CLI `sync` command only downloads **text files** (Markdown/JSON). It does _not_ download or execute binaries, scripts, or unknown code.
|
|
114
|
+
- **Transparent Operations**: The CLI simply fetches text files from the [official registry](https://github.com/HoangNguyen0403/agent-skills-standard) and copies them to your local `.agent/skills` folder. No background daemons or hidden network calls.
|
|
115
|
+
- **Privacy First**: We never collect usage telemetry or analytics. Feedback is only shared if you explicitly trigger it using `ags feedback`.
|
|
316
116
|
|
|
317
|
-
|
|
117
|
+
---
|
|
318
118
|
|
|
319
|
-
|
|
119
|
+
## ❓ FAQ & Links
|
|
320
120
|
|
|
321
|
-
|
|
121
|
+
<details>
|
|
122
|
+
<summary><b>Do I need to install this globally?</b></summary>
|
|
123
|
+
<br>
|
|
124
|
+
We recommend using <code>npx agent-skills-standard sync</code> to always use the latest version without global installation.
|
|
125
|
+
</details>
|
|
322
126
|
|
|
323
|
-
|
|
127
|
+
<details>
|
|
128
|
+
<summary><b>Does it overwrite my custom rules?</b></summary>
|
|
129
|
+
<br>
|
|
130
|
+
No. If you have custom rules in <code>.cursorrules</code> or other files, you can use the <code>custom_overrides</code> feature in your <code>.skillsrc</code> and the CLI will intelligently skip overwriting them.
|
|
131
|
+
</details>
|
|
324
132
|
|
|
325
|
-
|
|
133
|
+
<br>
|
|
326
134
|
|
|
327
|
-
|
|
135
|
+
### 🔗 Useful Links
|
|
328
136
|
|
|
329
137
|
- **Registry Source**: [GitHub Repository](https://github.com/HoangNguyen0403/agent-skills-standard)
|
|
330
138
|
- **CLI Architecture**: [Internal Services & Design](https://github.com/HoangNguyen0403/agent-skills-standard/blob/develop/cli/ARCHITECTURE.md)
|
|
331
139
|
- **Standard Specs**: [Documentation](https://github.com/HoangNguyen0403/agent-skills-standard#📂-standard-specification)
|
|
332
140
|
- **Issues**: [Report a bug](https://github.com/HoangNguyen0403/agent-skills-standard/issues)
|
|
333
141
|
|
|
334
|
-
|
|
142
|
+
#### 📜 Benchmark History
|
|
143
|
+
|
|
144
|
+
| Version | Date | Skills | Avg Tokens | Savings (%) | Report |
|
|
145
|
+
| --- | --- | --- | --- | --- | --- |
|
|
146
|
+
| v1.10.1 | 2026-03-16 | 229 | 428 | 88% | [Report](benchmarks/archive/v1.10.1.md) |
|
|
147
|
+
| v1.10.0 | 2026-03-16 | 229 | 434 | 88% | [Report](benchmarks/archive/v1.10.0.md) |
|
|
148
|
+
| v1.9.3 | 2026-03-15 | 229 | 460 | 87% | [Report](benchmarks/archive/v1.9.3.md) |
|
package/dist/index.js
CHANGED
|
@@ -971,16 +971,39 @@ class DetectionService {
|
|
|
971
971
|
* @returns A record of framework IDs and their detection status (boolean)
|
|
972
972
|
*/
|
|
973
973
|
async detectFrameworks() {
|
|
974
|
-
const
|
|
974
|
+
const cwd = process.cwd();
|
|
975
|
+
const dirsToScan = [cwd];
|
|
976
|
+
try {
|
|
977
|
+
const entries = await fs.readdir(cwd, { withFileTypes: true });
|
|
978
|
+
for (const entry of entries) {
|
|
979
|
+
if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
|
|
980
|
+
dirsToScan.push(path.join(cwd, entry.name));
|
|
981
|
+
}
|
|
982
|
+
}
|
|
983
|
+
} catch {
|
|
984
|
+
}
|
|
985
|
+
const packageDepsMaps = await Promise.all(
|
|
986
|
+
dirsToScan.map((dir) => this.readPackageJsonDeps(dir))
|
|
987
|
+
);
|
|
988
|
+
const allPackageDeps = {};
|
|
989
|
+
for (const deps of packageDepsMaps) {
|
|
990
|
+
Object.assign(allPackageDeps, deps);
|
|
991
|
+
}
|
|
975
992
|
const detectionPromises = SUPPORTED_FRAMEWORKS.map(async (framework) => {
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
993
|
+
let detected = false;
|
|
994
|
+
for (const dir of dirsToScan) {
|
|
995
|
+
if (detected) break;
|
|
996
|
+
const fileChecks = framework.detectionFiles.map(
|
|
997
|
+
(file) => fs.pathExists(path.join(dir, file))
|
|
998
|
+
);
|
|
999
|
+
const fileResults = await Promise.all(fileChecks);
|
|
1000
|
+
if (fileResults.some((exists) => exists)) {
|
|
1001
|
+
detected = true;
|
|
1002
|
+
}
|
|
1003
|
+
}
|
|
981
1004
|
if (!detected && framework.detectionDependencies && framework.detectionDependencies.length > 0) {
|
|
982
1005
|
detected = framework.detectionDependencies.some(
|
|
983
|
-
(dep) => Object.prototype.hasOwnProperty.call(
|
|
1006
|
+
(dep) => Object.prototype.hasOwnProperty.call(allPackageDeps, dep)
|
|
984
1007
|
);
|
|
985
1008
|
}
|
|
986
1009
|
return { id: framework.id, detected };
|
|
@@ -991,11 +1014,6 @@ class DetectionService {
|
|
|
991
1014
|
{}
|
|
992
1015
|
);
|
|
993
1016
|
}
|
|
994
|
-
/**
|
|
995
|
-
* Detects programming languages associated with a specific framework.
|
|
996
|
-
* @param framework The framework definition to use for detection
|
|
997
|
-
* @returns Array of detected language IDs
|
|
998
|
-
*/
|
|
999
1017
|
async detectLanguages(framework) {
|
|
1000
1018
|
if (!framework.languageDetection) {
|
|
1001
1019
|
return framework.languages;
|
|
@@ -1657,29 +1675,42 @@ class AgentBridgeService {
|
|
|
1657
1675
|
const relativeSkillsPath = path.relative(config.ruleFile, config.path).replace(/\\/g, "/");
|
|
1658
1676
|
const prefix = relativeSkillsPath ? `${relativeSkillsPath}/` : "";
|
|
1659
1677
|
const commonBody = [
|
|
1660
|
-
"# 🛠 Agent Skills
|
|
1678
|
+
"# 🛠 Agent Skills Routing Protocol (CRITICAL)",
|
|
1661
1679
|
"",
|
|
1662
|
-
"
|
|
1680
|
+
"You are operating in a Zero-Trust environment. You are strictly forbidden from relying on your baseline pre-training for architecture, styling, testing, or code patterns in this repository.",
|
|
1663
1681
|
"",
|
|
1664
|
-
"> [!
|
|
1665
|
-
"> **
|
|
1666
|
-
">
|
|
1682
|
+
"> [!CRITICAL] GATEKEEPER CONSTRAINT",
|
|
1683
|
+
"> **Your first action in ANY session MUST be a tool call to read `AGENTS.md`.**",
|
|
1684
|
+
"> You must NOT write code, suggest solutions, or output text explanations until you have completed the State Machine below.",
|
|
1667
1685
|
"",
|
|
1668
|
-
"##
|
|
1686
|
+
"## 🔄 The Mandatory State Machine",
|
|
1669
1687
|
"",
|
|
1670
|
-
"
|
|
1671
|
-
"> **DO NOT WRITE CODE OR ANSWER QUESTIONS UNTIL YOU HAVE COMPLETED THESE STEPS. This is a mandatory pre-flight checklist.**",
|
|
1688
|
+
"You must execute these states sequentially. Do not proceed to the next state until the current one is satisfied.",
|
|
1672
1689
|
"",
|
|
1673
|
-
"
|
|
1674
|
-
"2. **Step 2: Compare Context** → Check the user's prompt (keywords) and involved files (globs) against the index triggers.",
|
|
1675
|
-
"3. **Step 3: Load Skills** → Call `view_file` to read the full `SKILL.md` for _every_ matching skill.",
|
|
1676
|
-
"4. **Step 4: Audit Output** → Before writing or editing any code, verify your proposed solution adheres to the loaded skills.",
|
|
1690
|
+
"### State 1: Discovery (Tool Call Required)",
|
|
1677
1691
|
"",
|
|
1678
|
-
"
|
|
1692
|
+
"- **Action:** Execute a file-reading tool (e.g., `view_file`, `read_file`, `cat`) targeting the exact path: `AGENTS.md` (located in the project root).",
|
|
1693
|
+
"- **Condition to pass:** You have successfully read the `<!-- SKILLS_INDEX_START -->` block.",
|
|
1694
|
+
"",
|
|
1695
|
+
"### State 2: Trigger Matching (Internal Thought)",
|
|
1696
|
+
"",
|
|
1697
|
+
"- **Action:** Analyze the user's prompt (keywords) and the files involved in the task (globs).",
|
|
1698
|
+
"- **Condition to pass:** Cross-reference them against the `(triggers: ...)` list inside `AGENTS.md`. Identify all matching Skills and note their exact file paths.",
|
|
1699
|
+
"",
|
|
1700
|
+
"### State 3: Context Loading (Tool Call Required)",
|
|
1701
|
+
"",
|
|
1702
|
+
`- **Action:** Execute file-reading tools to read the \`SKILL.md\` files at the exact paths identified in State 2.`,
|
|
1703
|
+
"- **Condition to pass:** You have ingested the specific guidelines for the task. If no skills matched in State 2, you may skip this state.",
|
|
1704
|
+
"",
|
|
1705
|
+
"### State 4: Execution & Audit Log (Output Generation)",
|
|
1706
|
+
"",
|
|
1707
|
+
"- **Action:** You may now begin answering the user or writing code.",
|
|
1708
|
+
'- **Constraint:** Your very first text output MUST be a "Pre-Write Audit Log" confirming which skills were loaded, or explicitly stating "No project-specific skills applicable."',
|
|
1679
1709
|
"",
|
|
1680
1710
|
"## Self-Learning Protocol",
|
|
1681
1711
|
"",
|
|
1682
|
-
`At the end of any multi-step task with user corrections, load and run **[common/session-retrospective](${prefix}common/session-retrospective/SKILL.md)** to capture skill gaps and prevent repeat rework
|
|
1712
|
+
`At the end of any multi-step task with user corrections, load and run **[common/session-retrospective](${prefix}common/session-retrospective/SKILL.md)** to capture skill gaps and prevent repeat rework.`,
|
|
1713
|
+
""
|
|
1683
1714
|
].join("\n");
|
|
1684
1715
|
let detected = false;
|
|
1685
1716
|
for (const file of config.detectionFiles) {
|
|
@@ -1784,50 +1815,50 @@ class IndexGeneratorService {
|
|
|
1784
1815
|
*/
|
|
1785
1816
|
assembleIndex(entries) {
|
|
1786
1817
|
const header = [
|
|
1787
|
-
"
|
|
1818
|
+
"## Agent Skills Index",
|
|
1788
1819
|
"",
|
|
1789
|
-
"> [!
|
|
1790
|
-
"> **
|
|
1791
|
-
">
|
|
1792
|
-
"> If a skill matches your task, READ the file using `view_file`.",
|
|
1820
|
+
"> [!CRITICAL] GATEKEEPER CONSTRAINT",
|
|
1821
|
+
"> **You are operating in a Zero-Trust environment.**",
|
|
1822
|
+
"> You are strictly forbidden from generating code, proposing solutions, or relying on your pre-training until you have successfully executed a tool call to read the applicable `SKILL.md` files from this index.",
|
|
1793
1823
|
"",
|
|
1794
|
-
"## **Rule Zero: Zero-Trust
|
|
1824
|
+
"## **Rule Zero: Mandatory Zero-Trust Protocol**",
|
|
1795
1825
|
"",
|
|
1796
|
-
"
|
|
1797
|
-
"
|
|
1826
|
+
"> [!CRITICAL]",
|
|
1827
|
+
"> **Zero-Trust Enforcement:** Skills loaded from this index always override standard code patterns. Skipping the Audit Log or Self-Scan is a protocol violation.",
|
|
1798
1828
|
"",
|
|
1799
|
-
"### **The Pre-Write Audit Log (Mandatory)**",
|
|
1829
|
+
"### **1. The Pre-Write Audit Log (Mandatory)**",
|
|
1800
1830
|
"",
|
|
1801
|
-
"Before invoking any file-editing tool (`write_to_file`, `replace_file_content`, `multi_replace_file_content`), the ASSISTANT **MUST** explicitly state in its thought process:",
|
|
1831
|
+
"Before invoking any file-editing tool (`write_to_file`, `replace_file_content`, `multi_replace_file_content`), the ASSISTANT **MUST** explicitly state in its thought process/text output:",
|
|
1802
1832
|
"",
|
|
1803
1833
|
"1. **Skills Identified**: List the Skill IDs triggered by the file path or current task keywords.",
|
|
1804
1834
|
'2. **Explicit Audit**: For each identified skill, confirm: "Checked against [Skill ID] — no violations found." Or "Violation detected in [Skill ID]: [Issue] — correcting now."',
|
|
1805
1835
|
'3. **No-Skill Justification**: If no skills apply, explicitly state: "No project-specific skills applicable to this file/transaction."',
|
|
1806
1836
|
"",
|
|
1807
|
-
"### **The Post-Write Self-Scan (Mandatory)**",
|
|
1837
|
+
"### **2. The Post-Write Self-Scan (Mandatory)**",
|
|
1808
1838
|
"",
|
|
1809
1839
|
"Immediately **AFTER** any file-editing tool returns, the ASSISTANT **MUST**:",
|
|
1810
1840
|
"",
|
|
1811
1841
|
"1. **Validate**: Contrast the final file content against ALL active Skill IDs.",
|
|
1812
1842
|
'2. **Identify Slips**: Look for "Standard Defaults" (e.g., local mocks, hardcoded styles) that snuck in.',
|
|
1813
|
-
"3. **Self-Correct**: If a violation is found, fix it immediately in the next tool call.
|
|
1843
|
+
"3. **Self-Correct**: If a violation is found, fix it immediately in the next tool call.",
|
|
1814
1844
|
"",
|
|
1815
1845
|
"## **Critical Anti-Patterns (Zero-Tolerance)**",
|
|
1816
1846
|
"",
|
|
1817
|
-
'- **Reversion to Defaults**: Never use "standard" patterns (generic library calls, local mocks) if a Project Skill
|
|
1847
|
+
'- **Reversion to Defaults**: Never use "standard" patterns (generic library calls, local mocks) if a Project Skill exists.',
|
|
1818
1848
|
'- **The "Done" Trap**: Never prioritize functional completion over structural/protocol compliance.',
|
|
1819
1849
|
"- **Audit Skipping**: Never invoke a write tool without an explicit Pre-Write Audit Log.",
|
|
1820
1850
|
"",
|
|
1821
|
-
"## ⚡ How to Use This Index (Mandatory)",
|
|
1851
|
+
"## ⚡ How to Find and Use This Index (Mandatory)",
|
|
1822
1852
|
"",
|
|
1823
|
-
"> [!
|
|
1824
|
-
">
|
|
1825
|
-
">
|
|
1853
|
+
"> [!IMPORTANT] PATH RESOLUTION (Cross-Platform)",
|
|
1854
|
+
"> Skill IDs in the list below (e.g., `[category/skill-name]`) represent the relative folder path.",
|
|
1855
|
+
"> Because this project supports multiple AI agents, skills may reside in a base directory like `.gemini/skills/`, `.agent/skills/`, or `.cursor/skills/`.",
|
|
1856
|
+
"> **Action:** You must prepend the correct base directory to the ID. (Example: If ID is `[flutter/cicd]`, the file is at `<BASE_DIR>/flutter/cicd/SKILL.md`). Use your file search tools (e.g., `list_directory` or `find`) if you are unsure of the base directory.",
|
|
1826
1857
|
"",
|
|
1827
1858
|
"| Trigger Type | What to match | Required Action |",
|
|
1828
|
-
"
|
|
1829
|
-
"| **File glob** (e.g. `**/*.ts`) | Files you are currently editing match the pattern | Call `view_file` on
|
|
1830
|
-
"| **Keyword** (e.g. `auth`, `refactor`) | These words appear in the user\\'s request | Call `view_file` on
|
|
1859
|
+
"| --- | --- | --- |",
|
|
1860
|
+
"| **File glob** (e.g. `**/*.ts`) | Files you are currently editing match the pattern | Call `view_file` on `<BASE_DIR>/[Skill ID]/SKILL.md` |",
|
|
1861
|
+
"| **Keyword** (e.g. `auth`, `refactor`) | These words appear in the user\\'s request | Call `view_file` on `<BASE_DIR>/[Skill ID]/SKILL.md` |",
|
|
1831
1862
|
"| **Composite** (e.g. `+other/skill`) | Another listed skill is already active | Also load this skill via `view_file` |",
|
|
1832
1863
|
"",
|
|
1833
1864
|
"> [!TIP]",
|
|
@@ -1892,8 +1923,10 @@ ${entries.join("\n")}
|
|
|
1892
1923
|
...allComposites.length ? allComposites.map((c) => `+${c}`) : [],
|
|
1893
1924
|
...metadata.triggers.exclude ? metadata.triggers.exclude.map((e) => `!${e}`) : []
|
|
1894
1925
|
].join(", ");
|
|
1895
|
-
const triggerText = triggers ? ` (triggers:
|
|
1896
|
-
|
|
1926
|
+
const triggerText = triggers ? ` (triggers: \`${triggers}\`)` : "";
|
|
1927
|
+
let desc = metadata.description || "";
|
|
1928
|
+
desc = desc.replace(/\(triggers:\s*`?(.*?)`?\)/g, "(triggers: `$1`)");
|
|
1929
|
+
const content = `${prefix}${desc}`.trim();
|
|
1897
1930
|
return `- **[${id}]**: ${content}${triggerText}`;
|
|
1898
1931
|
}
|
|
1899
1932
|
}
|
|
@@ -1945,11 +1978,35 @@ class SkillSyncService {
|
|
|
1945
1978
|
*/
|
|
1946
1979
|
async writeSkills(skills, config, agents) {
|
|
1947
1980
|
const overrides = config.custom_overrides || [];
|
|
1981
|
+
const fetchedSkillsByCategory = {};
|
|
1982
|
+
for (const skill of skills) {
|
|
1983
|
+
if (!fetchedSkillsByCategory[skill.category]) {
|
|
1984
|
+
fetchedSkillsByCategory[skill.category] = /* @__PURE__ */ new Set();
|
|
1985
|
+
}
|
|
1986
|
+
fetchedSkillsByCategory[skill.category].add(skill.skill);
|
|
1987
|
+
}
|
|
1948
1988
|
for (const agentId of agents) {
|
|
1949
1989
|
const agentDef = SUPPORTED_AGENTS.find((a) => a.id === agentId);
|
|
1950
1990
|
if (!agentDef || !agentDef.path) continue;
|
|
1951
1991
|
const basePath = agentDef.path;
|
|
1952
1992
|
await fs.ensureDir(basePath);
|
|
1993
|
+
const shouldPrune = config.prune !== false;
|
|
1994
|
+
if (shouldPrune) {
|
|
1995
|
+
for (const category of Object.keys(fetchedSkillsByCategory)) {
|
|
1996
|
+
const categoryPath = path.join(basePath, category);
|
|
1997
|
+
if (await fs.pathExists(categoryPath)) {
|
|
1998
|
+
const existingDirs = await fs.readdir(categoryPath);
|
|
1999
|
+
for (const dir of existingDirs) {
|
|
2000
|
+
if (!fetchedSkillsByCategory[category].has(dir)) {
|
|
2001
|
+
const fullPath = path.join(categoryPath, dir);
|
|
2002
|
+
if (!this.isOverridden(fullPath, overrides)) {
|
|
2003
|
+
await fs.remove(fullPath);
|
|
2004
|
+
}
|
|
2005
|
+
}
|
|
2006
|
+
}
|
|
2007
|
+
}
|
|
2008
|
+
}
|
|
2009
|
+
}
|
|
1953
2010
|
for (const skill of skills) {
|
|
1954
2011
|
await this.writeSkillForAgent(agentId, skill, overrides, basePath);
|
|
1955
2012
|
}
|
|
@@ -2068,8 +2125,8 @@ description: ${description}
|
|
|
2068
2125
|
isOverridden(targetPath, overrides) {
|
|
2069
2126
|
const rel = this.normalizePath(targetPath);
|
|
2070
2127
|
return overrides.some((o) => {
|
|
2071
|
-
const op = o.replace(/\\/g, "/");
|
|
2072
|
-
return rel === op || rel.startsWith(`${op.
|
|
2128
|
+
const op = o.replace(/\\/g, "/").replace(/\/$/, "");
|
|
2129
|
+
return rel === op || rel.startsWith(`${op}/`) || rel.includes(`/${op}/`) || rel.endsWith(`/${op}`);
|
|
2073
2130
|
});
|
|
2074
2131
|
}
|
|
2075
2132
|
isPathSafe(targetPath, skillPath) {
|
|
@@ -2207,8 +2264,8 @@ class WorkflowSyncService {
|
|
|
2207
2264
|
isOverridden(targetPath, overrides) {
|
|
2208
2265
|
const rel = this.normalizePath(targetPath);
|
|
2209
2266
|
return overrides.some((o) => {
|
|
2210
|
-
const op = o.replace(/\\/g, "/");
|
|
2211
|
-
return rel === op || rel.startsWith(`${op.
|
|
2267
|
+
const op = o.replace(/\\/g, "/").replace(/\/$/, "");
|
|
2268
|
+
return rel === op || rel.startsWith(`${op}/`) || rel.includes(`/${op}/`) || rel.endsWith(`/${op}`);
|
|
2212
2269
|
});
|
|
2213
2270
|
}
|
|
2214
2271
|
normalizePath(p) {
|
|
@@ -2463,7 +2520,7 @@ class SyncCommand {
|
|
|
2463
2520
|
}
|
|
2464
2521
|
}
|
|
2465
2522
|
}
|
|
2466
|
-
const version = "1.
|
|
2523
|
+
const version = "1.10.2";
|
|
2467
2524
|
const pkg = {
|
|
2468
2525
|
version
|
|
2469
2526
|
};
|
|
@@ -2727,9 +2784,9 @@ class FrontmatterRule {
|
|
|
2727
2784
|
result.passed = false;
|
|
2728
2785
|
} else {
|
|
2729
2786
|
const descMatch = frontmatter.match(/description:\s*(.+)/);
|
|
2730
|
-
if (descMatch && descMatch[1].length >
|
|
2787
|
+
if (descMatch && descMatch[1].length > 1024) {
|
|
2731
2788
|
result.errors.push(
|
|
2732
|
-
`Description too long (${descMatch[1].length} chars >
|
|
2789
|
+
`Description too long (${descMatch[1].length} chars > 1024 limit)`
|
|
2733
2790
|
);
|
|
2734
2791
|
result.passed = false;
|
|
2735
2792
|
}
|
|
@@ -2981,7 +3038,7 @@ dotenv.config();
|
|
|
2981
3038
|
const program = new commander.Command();
|
|
2982
3039
|
program.name("agent-skills-standard").description(
|
|
2983
3040
|
"A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, Windsurf, and more."
|
|
2984
|
-
).version("1.
|
|
3041
|
+
).version("1.10.2");
|
|
2985
3042
|
program.command("init").description("Initialize a .skillsrc configuration file interactively").action(async () => {
|
|
2986
3043
|
const init = new InitCommand();
|
|
2987
3044
|
await init.run();
|