agent-skills-standard 1.9.2 β 1.10.0
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 +58 -180
- package/dist/index.js +405 -320
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,192 +1,84 @@
|
|
|
1
|
-
# Agent Skills Standard CLI π
|
|
1
|
+
# Agent Skills Standard CLI: Deployment & Sync Engine π
|
|
2
2
|
|
|
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
|
-
**The engine
|
|
6
|
+
**The heavy-lifting engine for High-Density AI Agent Instructions. Deploy professional standards to any project in seconds.**
|
|
7
7
|
|
|
8
|
-
The `agent-skills-standard` CLI is the official command-line tool to manage, sync, and version-control engineering standards across all major AI agents (**Cursor, Claude Code, GitHub Copilot, Gemini, Roo Code,
|
|
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**).
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## π Table of Contents
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
- [π‘ What does this tool do?](#-what-does-this-tool-do)
|
|
15
|
+
- [π The Solution: Digital DNA for AI](#-the-solution-digital-dna-for-ai)
|
|
16
|
+
- [π Installation & Quick Start](#-installation--quick-start)
|
|
17
|
+
- [βοΈ Configuration (`.skillsrc`)](#οΈ-configuration-skillsrc)
|
|
18
|
+
- [π Privacy & Security](#-privacy--security)
|
|
19
|
+
- [β FAQ & Links](#-faq--links)
|
|
15
20
|
|
|
16
|
-
|
|
21
|
+
---
|
|
17
22
|
|
|
18
|
-
|
|
19
|
-
- **For Non-IT/Tech Leads**: Quickly set up a new project with the same professional standards used by senior engineers.
|
|
20
|
-
- **For Teams**: Ensure every developerβs AI tool (Cursor, Claude, Copilot) behaves the same way across the entire codebase.
|
|
23
|
+
## π‘ What does this tool do?
|
|
21
24
|
|
|
22
|
-
|
|
25
|
+
If the **Agent Skills Standard** is the "instruction manual" for your AI, this CLI is the **delivery engine** that brings those instructions to your project.
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
### π― Who is this for?
|
|
25
28
|
|
|
26
|
-
|
|
29
|
+
| Role | Benefit |
|
|
30
|
+
| :------------------- | :---------------------------------------------------------------------------------- |
|
|
31
|
+
| **π Builders** | No more copy-pasting `.cursorrules`. One command syncs your entire AI workspace. |
|
|
32
|
+
| **π‘οΈ Architects** | Push global engineering standards to every developer's IDE automatically. |
|
|
33
|
+
| **π Organizations** | Standardize AI behavior across your company. Ensure every agent "knows" your stack. |
|
|
27
34
|
|
|
28
|
-
|
|
29
|
-
2. **Version Chaos**: Team members often have different "best practices," leading to inconsistent code.
|
|
30
|
-
3. **Wordy Prose**: Human-style instructions are token-heavy and often ignored by AI during complex logical tasks.
|
|
35
|
+
### π CLI Sync Workflow
|
|
31
36
|
|
|
32
|
-
|
|
37
|
+
```mermaid
|
|
38
|
+
graph LR
|
|
39
|
+
A[Developers] -- run ags sync --> B[CLI Engine]
|
|
40
|
+
B -- fetch --> C[Cloud Registry]
|
|
41
|
+
C -- deploy --> D[Local IDE Settings]
|
|
42
|
+
D -- power-up --> E[Expert AI Coding]
|
|
43
|
+
|
|
44
|
+
style E fill:#dcfce7,stroke:#166534
|
|
45
|
+
```
|
|
33
46
|
|
|
34
47
|
---
|
|
35
48
|
|
|
36
49
|
## π The Solution: Digital DNA for AI
|
|
37
50
|
|
|
38
|
-
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**.
|
|
39
52
|
|
|
40
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.
|
|
41
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.
|
|
42
55
|
- **π One-Click Sync**: A single command ensures your AI tool stays up-to-date with your team's latest standards.
|
|
43
56
|
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## π‘οΈ Security & Trust
|
|
47
|
-
|
|
48
|
-
We take security seriously. Here is what you need to know about how the CLI works:
|
|
49
|
-
|
|
50
|
-
- **No Hidden Scripts**: The CLI `sync` command only downloads **text files** (Markdown/JSON). It does _not_ download or execute binaries, scripts, or unknown code.
|
|
51
|
-
- **No "Code Injection"**: When we say "injection", we mean **Prompt Injection** (adding context to the AI's conversation history), NOT code injection (running malware).
|
|
52
|
-
- **Transparent Operations**:
|
|
53
|
-
- The CLI fetches a standard directory structure from the [official registry](https://github.com/HoangNguyen0403/agent-skills-standard).
|
|
54
|
-
- It copies these text files to your local `.cursor/skills` or `.agent/skills` folder.
|
|
55
|
-
- It updates `AGENTS.md` (a text file index).
|
|
56
|
-
- **That is it.** No background services, no daemons, no hidden network calls.
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## π Efficiency & Benchmark
|
|
61
|
-
|
|
62
|
-
Every skill delivered by this CLI is audited for its footprint in the AI's context window.
|
|
63
|
-
|
|
64
|
-
| Metric | Savings (vs. Heavy Prompt) | Avg. Footprint | Quality |
|
|
65
|
-
| ------------------ | -------------------------: | -------------- | ------- |
|
|
66
|
-
| **Global Average** | **88% Savings** | ~457 tokens | 8.9/10 |
|
|
67
|
-
|
|
68
57
|
> [!IMPORTANT]
|
|
69
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.
|
|
70
59
|
|
|
71
|
-
- **π‘οΈ Multi-Agent Support**: Out-of-the-box mapping for Cursor, Claude Dev, GitHub Copilot, and more.
|
|
72
|
-
- **π¦ Modular Registry**: Don't load everything. Only enable the skills your project actually uses.
|
|
73
|
-
- **β‘ Proactive Activation (Universal)**: Generates a compressed index in `AGENTS.md` for 100% activation reliability across Cursor, Windsurf, Claude Code, and more.
|
|
74
|
-
- **π Dynamic Re-detection**: Automatically re-enables skills if matching dependencies are added.
|
|
75
|
-
- **π Secure Overrides**: Lock specific files so they never get overwritten.
|
|
76
|
-
- **π Semantic Tagging**: Skills tagged with triggers for exact application.
|
|
77
|
-
- **π€ Agent Workflows**: Sync executable workflows (.md files) that agents can follow to perform complex tasks.
|
|
78
|
-
|
|
79
60
|
---
|
|
80
61
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
| Version | Date | Skills | Avg Tokens | Savings (%) | Report |
|
|
84
|
-
| ------- | ---------- | ------ | ---------- | ----------- | -------------------------------------- |
|
|
85
|
-
| v1.9.2 | 2026-03-07 | 228 | 458 | 87% | [Report](benchmarks/archive/v1.9.2.md) |
|
|
86
|
-
| v1.9.1 | 2026-03-07 | 228 | 458 | 87% | [Report](benchmarks/archive/v1.9.1.md) |
|
|
87
|
-
| v1.9.0 | 2026-03-05 | 228 | 457 | 88% | [Report](benchmarks/archive/v1.9.0.md) |
|
|
88
|
-
| v1.8.0 | 2026-03-02 | 228 | 443 | 88% | [Report](benchmarks/archive/v1.8.0.md) |
|
|
89
|
-
|
|
90
|
-
## οΏ½ Token Economy & Optimization
|
|
91
|
-
|
|
92
|
-
To ensure AI efficiency, this project follows a strict **Token Economy**. Every skill is audited for its footprint in the AI's context window.
|
|
93
|
-
|
|
94
|
-
### π Our Standards
|
|
95
|
-
|
|
96
|
-
- **High-Density**: Core rules in `SKILL.md` are kept under **100 lines**.
|
|
97
|
-
- **Efficiency**: Target **< 500 tokens** per primary skill file.
|
|
98
|
-
- **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.
|
|
99
|
-
|
|
100
|
-
## π Privacy & Feedback
|
|
101
|
-
|
|
102
|
-
### Feedback Reporter Skill
|
|
103
|
-
|
|
104
|
-
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.**
|
|
105
|
-
|
|
106
|
-
**What Gets Shared (Only if AI Agent Report):**
|
|
107
|
-
|
|
108
|
-
- Skill category/name
|
|
109
|
-
- Issue description (written by you or generated by AI)
|
|
110
|
-
- **Skill Instruction**: Exact quote from the skill that was violated
|
|
111
|
-
- **Actual Action**: What the AI did instead
|
|
112
|
-
- **Decision Reason**: Why the AI chose that approach
|
|
113
|
-
- Optional context (framework version, scenario)
|
|
114
|
-
- Optional AI Model name
|
|
115
|
-
- **NO code, NO project details, NO personal information**
|
|
116
|
-
|
|
117
|
-
**How to Opt-Out:**
|
|
118
|
-
Add to `.skillsrc`:
|
|
119
|
-
|
|
120
|
-
```yaml
|
|
121
|
-
skills:
|
|
122
|
-
common:
|
|
123
|
-
exclude: ['feedback-reporter']
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
**How to Report Issues:**
|
|
127
|
-
Use structured comments:
|
|
128
|
-
|
|
129
|
-
```typescript
|
|
130
|
-
// @agent-skills-feedback
|
|
131
|
-
// Skill: react/hooks
|
|
132
|
-
// Issue: AI suggested unsafe pattern
|
|
133
|
-
// Suggestion: Add guidance for this case
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
**Privacy First**: We never collect usage telemetry or analytics. Feedback is only shared if you explicitly trigger it.
|
|
137
|
-
|
|
138
|
-
#### Manual Feedback
|
|
139
|
-
|
|
140
|
-
If you notice a skill needs improvement, you can manually send feedback using:
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
ags feedback
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
Or via structured comments in your code:
|
|
147
|
-
|
|
148
|
-
```typescript
|
|
149
|
-
// @agent-skills-feedback
|
|
150
|
-
// Skill: react/hooks
|
|
151
|
-
// Issue: AI suggested unsafe pattern
|
|
152
|
-
// Suggestion: Add guidance for this case
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
## π Installation
|
|
62
|
+
## π Installation & Quick Start
|
|
156
63
|
|
|
157
64
|
You can run the tool instantly without installing, or install it globally for convenience:
|
|
158
65
|
|
|
159
66
|
```bash
|
|
160
67
|
# Use instantly (Recommended)
|
|
68
|
+
npx agent-skills-standard@latest init
|
|
161
69
|
npx agent-skills-standard@latest sync
|
|
162
70
|
|
|
163
71
|
# Or install globally
|
|
164
72
|
npm install -g agent-skills-standard
|
|
165
|
-
|
|
166
|
-
# Use the short alias
|
|
167
73
|
ags sync
|
|
168
74
|
```
|
|
169
75
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
## π Basic Commands
|
|
76
|
+
### π Basic Commands
|
|
173
77
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
npx agent-skills-standard@latest init
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
### 2. Boost Your AI
|
|
183
|
-
|
|
184
|
-
Run this to fetch the latest high-density instructions and install them into your hidden agent folders (like `.cursor/skills/` or `.github/skills/`).
|
|
185
|
-
|
|
186
|
-
```bash
|
|
187
|
-
npx agent-skills-standard@latest sync
|
|
188
|
-
|
|
189
|
-
```
|
|
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.
|
|
190
82
|
|
|
191
83
|
---
|
|
192
84
|
|
|
@@ -202,61 +94,47 @@ skills:
|
|
|
202
94
|
ref: flutter-v1.1.0
|
|
203
95
|
# π« Exclude specific sub-skills from being synced
|
|
204
96
|
exclude: ['getx-navigation']
|
|
205
|
-
# β Include specific skills (supports cross-category 'category/skill'
|
|
97
|
+
# β Include specific skills (supports cross-category 'category/skill' syntax)
|
|
206
98
|
include:
|
|
207
99
|
- 'bloc-state-management'
|
|
208
100
|
- 'react/hooks'
|
|
209
|
-
- 'common/*'
|
|
210
101
|
# π Protect local modifications from being overwritten
|
|
211
102
|
custom_overrides: ['bloc-state-management']
|
|
212
103
|
# π€ Optional: Sync workflows to .agent/workflows/
|
|
213
104
|
workflows: true
|
|
214
105
|
```
|
|
215
106
|
|
|
216
|
-
|
|
107
|
+
---
|
|
217
108
|
|
|
218
|
-
|
|
219
|
-
- **`include`**: A list of skill IDs to fetch. Supports:
|
|
220
|
-
- **Relative Path**: `bloc-state-management` (from current category)
|
|
221
|
-
- **Absolute Path**: `react/hooks` (pull specific skill from another category)
|
|
222
|
-
- **Glob Path**: `common/*` (pull ALL skills from another category)
|
|
223
|
-
- **`custom_overrides`**: A list of skill IDs that the CLI should **never** overwrite.
|
|
224
|
-
- **`ref`**: Specify a specific version or tag for the skills.
|
|
109
|
+
## π Privacy & Security
|
|
225
110
|
|
|
226
|
-
|
|
111
|
+
We take security seriously. Here is what you need to know:
|
|
227
112
|
|
|
228
|
-
|
|
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`.
|
|
229
116
|
|
|
230
|
-
|
|
231
|
-
- **π High-Density Instructions**: Optimized syntax that is **40% more compact** than standard English.
|
|
232
|
-
- **π‘οΈ Universal Support**: Works out-of-the-box with Cursor, Claude, GitHub Copilot, and more.
|
|
233
|
-
- **π Secure Protection**: Mark specific files as "Locked" (overrides) so the CLI never changes your custom tweaks.
|
|
234
|
-
- **π§ͺ Production-Grade Reliability**: Guarded by a 100% statement coverage test suite and strict CI enforcement.
|
|
117
|
+
---
|
|
235
118
|
|
|
236
|
-
|
|
119
|
+
## β FAQ & Links
|
|
237
120
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
| **React** | 90% | `401`  | β
Stable |
|
|
244
|
-
| **Golang** | 90% | `375`  | β
Stable |
|
|
245
|
-
| **Android** | 92% | `295`  | β
Production |
|
|
246
|
-
| **iOS** | 90% | `411`  | β
Production |
|
|
247
|
-
| **Laravel** | 91% | `361`  | β
Stable |
|
|
248
|
-
| **Spring Boot** | 92% | `369`  | β
Stable |
|
|
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>
|
|
249
126
|
|
|
250
|
-
>
|
|
251
|
-
>
|
|
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>
|
|
252
132
|
|
|
253
|
-
|
|
133
|
+
<br>
|
|
254
134
|
|
|
255
|
-
|
|
135
|
+
### π Useful Links
|
|
256
136
|
|
|
257
137
|
- **Registry Source**: [GitHub Repository](https://github.com/HoangNguyen0403/agent-skills-standard)
|
|
258
138
|
- **CLI Architecture**: [Internal Services & Design](https://github.com/HoangNguyen0403/agent-skills-standard/blob/develop/cli/ARCHITECTURE.md)
|
|
259
139
|
- **Standard Specs**: [Documentation](https://github.com/HoangNguyen0403/agent-skills-standard#π-standard-specification)
|
|
260
140
|
- **Issues**: [Report a bug](https://github.com/HoangNguyen0403/agent-skills-standard/issues)
|
|
261
|
-
|
|
262
|
-
---
|