agent-skills-standard 2.6.3 → 2.6.5
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 +100 -1
- package/dist/index.js +4909 -2214
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
**Sync 242 AI coding standards to any project in one command.** Works with Cursor, Claude Code, GitHub Copilot, Gemini, Windsurf, Trae, Kiro, and Roo.
|
|
7
7
|
|
|
8
|
-
**Current release:** `v2.6.
|
|
8
|
+
**Current release:** `v2.6.5` — `ags sync` manifest-check fix for repo-root LICENSE/NOTICE; skill validator accepts package directories under `scripts/`; SkillSpector security scanning, pull request evaluation gates, and verified release tags.
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
11
|
npx agent-skills-standard@latest init # detect your stack
|
|
@@ -44,7 +44,55 @@ The result: your AI agent reads `AGENTS.md`, follows the router to the right cat
|
|
|
44
44
|
| `validate` | Checks your custom skills against format and token standards |
|
|
45
45
|
| `feedback` | Submits improvement suggestions to the registry |
|
|
46
46
|
| `upgrade` | Updates the CLI to the latest version |
|
|
47
|
+
| `doctor` | Check installation health (config, agents, lock file, MCP, hooks, CLI version) with human or JSON output and safe repairs |
|
|
48
|
+
| `restore` | List backups in `.ags/backups` or restore one (replace-only) |
|
|
49
|
+
| `uninstall` | Remove files ags installed (keeps files you edited); backs up first |
|
|
50
|
+
| `verify` | Check installed files against `.skills-lock.json` (`--strict`, `--attestation`) |
|
|
51
|
+
| `policy` | Manage and check project agent policies (status, check, validate, compile, adopt) |
|
|
47
52
|
|
|
53
|
+
|
|
54
|
+
### Install Safety & Sync Options
|
|
55
|
+
|
|
56
|
+
`ags sync` safely tracks owned files in `.skills-lock.json` v2 and preserves local user edits:
|
|
57
|
+
|
|
58
|
+
- **User-Edit Preservation**: If you edited a synced skill, workflow, specialist, or bridge file, sync keeps your version and warns instead of overwriting it.
|
|
59
|
+
- `--dry-run`: Preview additions, updates, kept edits, and prunes without writing anything to disk or modifying configs.
|
|
60
|
+
- `--dry-run --verbose`: List every affected file path by status.
|
|
61
|
+
- `--dry-run --json`: Emit the full install plan as machine-readable JSON (`schema_version: 1, kind: 'sync.plan'`).
|
|
62
|
+
- `--force <paths...>`: Overwrite specified user-edited files with upstream versions (a backup is created first).
|
|
63
|
+
- **Automatic Backups**: Destructive changes (pruning or forced overwrites) automatically snapshot previous files into `.ags/backups/<timestamp>/` (retaining the 3 most recent backups).
|
|
64
|
+
|
|
65
|
+
### Restore & Uninstall
|
|
66
|
+
|
|
67
|
+
- `ags restore [--list] [id]`: List backups or restore files from `.ags/backups/<id>` (replace-only; does not delete newer files or modify lockfile).
|
|
68
|
+
- `ags uninstall [--agent <agents...>] [--category <categories...>] [--all] [--dry-run] [-y, --yes]`:
|
|
69
|
+
- Removes only manifest entries whose on-disk sha256 still matches (owned-unchanged).
|
|
70
|
+
- Keeps user-edited files byte-identical.
|
|
71
|
+
- Automatically creates a backup of removed files and `.skills-lock.json` before deleting.
|
|
72
|
+
- `--all` removes all owned files, cleans MCP and hook registrations, clears `AGENTS.md` index block, and deletes `.skills-lock.json`. `CLAUDE.md` and `.skillsrc` are left unchanged.
|
|
73
|
+
- Non-interactive environments without `--yes` exit 1 with a preview.
|
|
74
|
+
|
|
75
|
+
### Verification: `ags verify`
|
|
76
|
+
|
|
77
|
+
Check installed files against `.skills-lock.json` to detect tampering, partial writes, or manual drift:
|
|
78
|
+
|
|
79
|
+
- `ags verify`: Checks file integrity against the lockfile.
|
|
80
|
+
- `ags verify --strict`: In addition to file integrity, fails (exit 1) if any locked ref now resolves to a different commit (moved tag) or cannot be resolved.
|
|
81
|
+
- `ags verify --attestation`: Verifies build-provenance attestations using the GitHub CLI (`gh`). Requires `gh` on PATH; fails if any pinned source lacks `MANIFEST.json` or fails attestation.
|
|
82
|
+
|
|
83
|
+
### Policy Layer: `ags policy`
|
|
84
|
+
|
|
85
|
+
Prevents mistakes by cooperating agents; not a security boundary.
|
|
86
|
+
|
|
87
|
+
Manage and check deterministic project rules in `.ags/policy.json` (`protected_path`, `command`, `required_check`):
|
|
88
|
+
|
|
89
|
+
- `ags policy status [--json]`: Show policy rules in force and built-in rules (identity/secret deny-list).
|
|
90
|
+
- `ags policy check (--path <p> | --command <cmd> | --diff) [--no-bypass] [--json]`: Evaluate a path, command executable, or git diff against active policy rules.
|
|
91
|
+
- `ags policy validate [--fail-on-stale] [--json]`: Validate `.ags/policy.json` for schema errors, rule conflicts, and stale compiled rules.
|
|
92
|
+
- `ags policy compile [--json]`: Scan `AGENTS.md` and `CLAUDE.md` to propose candidate rules into `.ags/policy-candidates.json`. Compiled rules can only warn or rewrite.
|
|
93
|
+
- `ags policy adopt <ids...> [--json]`: Activate candidate rules into `.ags/policy.json` after conflict validation.
|
|
94
|
+
|
|
95
|
+
Set `AGS_POLICY_BYPASS=1` (or `AGS_POLICY_BYPASS=true`) to turn policy decisions into allow while reporting waived rules.
|
|
48
96
|
---
|
|
49
97
|
|
|
50
98
|
## Configuration
|
|
@@ -54,6 +102,8 @@ The `.skillsrc` file controls everything:
|
|
|
54
102
|
```yaml
|
|
55
103
|
registry: https://github.com/HoangNguyen0403/agent-skills-standard
|
|
56
104
|
agents: [cursor, copilot, claude]
|
|
105
|
+
workflows_ref: workflows-v1.0.0 # pinned workflows release tag
|
|
106
|
+
specialists_ref: specialists-v2.0.0 # pinned specialists release tag
|
|
57
107
|
skills:
|
|
58
108
|
react:
|
|
59
109
|
ref: react-v1.3.1
|
|
@@ -65,6 +115,8 @@ skills:
|
|
|
65
115
|
custom_overrides: ['common-tdd'] # protect your local edits
|
|
66
116
|
```
|
|
67
117
|
|
|
118
|
+
A project without pins gets `workflows_ref` and `specialists_ref` written once to `.skillsrc` on first sync from the registry's latest releases (`--dry-run` never writes them). If the registry does not publish releases, sync falls back to the default branch with a warning.
|
|
119
|
+
|
|
68
120
|
---
|
|
69
121
|
|
|
70
122
|
## What Gets Generated
|
|
@@ -104,6 +156,53 @@ ags mcp uninstall --from project # remove our entry; siblings preserved
|
|
|
104
156
|
|
|
105
157
|
The CLI **never** modifies user-home files (`~/.cursor/mcp.json`, `~/.gemini/settings.json`, etc.) unless you explicitly choose `scope: user` AND confirm each write. See [`mcp/README.md`](../mcp/README.md) for full details and [`mcp/ARCHITECTURE.md`](../mcp/ARCHITECTURE.md) for the threat model.
|
|
106
158
|
|
|
159
|
+
|
|
160
|
+
## Installation Health: `ags doctor`
|
|
161
|
+
|
|
162
|
+
Run read-only health checks across seven subsystems: configuration (`.skillsrc`), detected/configured agents, skill-content lockfile (`.skills-lock.json`), MCP server registrations, pre-edit hooks, legacy folder migrations, and CLI version.
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
ags doctor # Human-readable health check report
|
|
166
|
+
ags doctor --offline # Skip the network-backed CLI version check
|
|
167
|
+
ags doctor --json # Emit a versioned JSON report (schema_version: 1, kind: 'doctor.report')
|
|
168
|
+
ags doctor --exit-on-fail # Exit with code 1 when any check fails (default exit code is 0)
|
|
169
|
+
ags doctor --fix # Apply available safe repairs interactively (prompts per fix)
|
|
170
|
+
ags doctor --fix --yes # Apply repairs non-interactively
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### JSON Envelope
|
|
174
|
+
|
|
175
|
+
When `--json` is supplied, `ags doctor` outputs a single JSON payload matching the `doctor.report` contract:
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"schema_version": 1,
|
|
180
|
+
"kind": "doctor.report",
|
|
181
|
+
"data": {
|
|
182
|
+
"schema_version": 1,
|
|
183
|
+
"checks": [
|
|
184
|
+
{
|
|
185
|
+
"name": "config",
|
|
186
|
+
"status": "ok",
|
|
187
|
+
"evidence": ".skillsrc parsed",
|
|
188
|
+
"fixable": false
|
|
189
|
+
}
|
|
190
|
+
],
|
|
191
|
+
"summary": {
|
|
192
|
+
"total": 7,
|
|
193
|
+
"ok": 7,
|
|
194
|
+
"warn": 0,
|
|
195
|
+
"fail": 0,
|
|
196
|
+
"skip": 0
|
|
197
|
+
},
|
|
198
|
+
"healthy": true
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Exit Behavior
|
|
204
|
+
|
|
205
|
+
`ags doctor` always exits with code `0` by default so it never unexpectedly breaks pipelines. When `--exit-on-fail` is passed, it exits with code `1` if any check produces a `fail` status (`healthy: false`).
|
|
107
206
|
---
|
|
108
207
|
|
|
109
208
|
## Privacy & Security
|