@csark0812/skeleton 1.0.0 → 1.1.1
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 +134 -3
- package/dist/cli.js +544 -81
- package/dist/hooks/customize-on-skill-read.js +6385 -13
- package/package.json +1 -1
- package/schemas/config.schema.json +16 -0
- package/templates/skeleton-init/config.yaml +6 -0
package/README.md
CHANGED
|
@@ -1,7 +1,138 @@
|
|
|
1
1
|
# Skeleton
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Single source of truth (SSOT) linter for agent-enabled repos.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Agent repos accumulate skills, rules, registries, and cross-linked docs faster than anyone can keep them straight by hand. Code repos solved this decades ago with ESLint — deterministic checks, CI gates, fix what you can before merge. Skeleton does the same job for documentation architecture: what's canonical, what links where, what must not exist, and whether your skill overrides are wired correctly.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Skeleton is **not** a runtime agent harness. It does not execute tools, enforce permissions, or manage agent memory. It is a CLI that audits docs, skills, and registries, and fails CI when invariants break.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
Code has linters. Agent repos need the same thing for docs and SSOT.
|
|
12
|
+
|
|
13
|
+
| Code repos | Agent repos |
|
|
14
|
+
| ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
15
|
+
| ESLint catches broken imports, unused vars, style drift | Skeleton catches broken links, missing registry rows, stale doc-meta, banned artifacts |
|
|
16
|
+
| `eslint --fix` on changed files | `skeleton validate changed` on changed docs and skills |
|
|
17
|
+
| Pre-commit + CI gate | `--staged` pre-commit + `--base` CI gate |
|
|
18
|
+
|
|
19
|
+
Skill linters (skillmark, agentlint, skillscheck) answer: _"Is this SKILL.md well-formed?"_ Skeleton answers: _"Does this repo's documentation system hold together?"_
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install -D @csark0812/skeleton
|
|
25
|
+
npx skeleton init --skills
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Init writes `.skeleton/`, merges validate scripts into `package.json`, and wires customize hooks for Cursor, Claude Code, and Codex.
|
|
29
|
+
|
|
30
|
+
Edit `.skeleton/config.yaml` for your repo layout, then verify:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx skeleton audit self
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
See [install](docs/developer/install.md) for flags and options.
|
|
37
|
+
|
|
38
|
+
## What it checks
|
|
39
|
+
|
|
40
|
+
- **Registry integrity** — `.skeleton/registry.md` topic → canonical file pointers; banner format on registered docs
|
|
41
|
+
- **Link audit** — broken refs, skill links, anchors in scanned markdown
|
|
42
|
+
- **Skill index** — disk matches taxonomy READMEs in detected skill roots
|
|
43
|
+
- **Banned paths** — session artifacts and other files that must not exist
|
|
44
|
+
- **Coverage gaps** — markdown outside the scan perimeter (warn-only)
|
|
45
|
+
- **Doc meta + stale dates** — owner and `last-reviewed` on index and registry-listed files
|
|
46
|
+
- **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
|
|
47
|
+
|
|
48
|
+
Code validation (TypeScript, Python, Nx, pytest) stays in your repo. Skeleton handles SSOT-adjacent paths only.
|
|
49
|
+
|
|
50
|
+
## The `.skeleton/` contract
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
.skeleton/
|
|
54
|
+
├── config.yaml # scan perimeter (required)
|
|
55
|
+
├── registry.md # topic → canonical file (required)
|
|
56
|
+
└── customize/ # project-specific skill overrides (optional)
|
|
57
|
+
└── code-review.md
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Every canonical doc carries a banner:
|
|
61
|
+
|
|
62
|
+
```markdown
|
|
63
|
+
**Source of truth for** Backend API conventions.
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Register it:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
skeleton register docs/developer/api.md
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Synced toolbox skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject via IDE hooks on skill read — no editing synced `SKILL.md` files.
|
|
73
|
+
|
|
74
|
+
## Commands
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
skeleton init [--skills] [--force-hooks]
|
|
78
|
+
skeleton register <path> [--topic=…]
|
|
79
|
+
skeleton audit docs|skills|self [--strict] [--paths=a,b]
|
|
80
|
+
skeleton validate changed [--staged | --base <ref>] [paths…]
|
|
81
|
+
skeleton customize resolve <slug>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**Validate changed** routes git diffs to the right audit:
|
|
85
|
+
|
|
86
|
+
| Path | Action |
|
|
87
|
+
| -------------------------------------------- | --------------------------- |
|
|
88
|
+
| Docs/skills in scan perimeter | path-scoped audit |
|
|
89
|
+
| `.sh`, `.bash`, `.zsh` | shellcheck or `bash -n` |
|
|
90
|
+
| Other `.json` | JSONC-tolerant syntax check |
|
|
91
|
+
| `.ts`, `.py`, `package.json`, `project.json` | skip |
|
|
92
|
+
|
|
93
|
+
Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
|
|
94
|
+
CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
|
|
95
|
+
|
|
96
|
+
## Ecosystem
|
|
97
|
+
|
|
98
|
+
Skeleton is the shared validation layer in a three-tier setup:
|
|
99
|
+
|
|
100
|
+
| Repo | Role |
|
|
101
|
+
| -------------------- | -------------------------------------------------- |
|
|
102
|
+
| **skeleton** | SSOT audit CLI (this repo) |
|
|
103
|
+
| **toolbox** | Team skills + public agent preferences |
|
|
104
|
+
| **personal-toolbox** | Private skills + personal preferences |
|
|
105
|
+
| **Consumer apps** | Call skeleton for SSOT; keep code validation local |
|
|
106
|
+
|
|
107
|
+
Skeleton never calls Nx or other task runners — consumers call skeleton for doc and skill paths, then handle code paths themselves.
|
|
108
|
+
|
|
109
|
+
See [tiers](docs/tiers.md).
|
|
110
|
+
|
|
111
|
+
## Distribution
|
|
112
|
+
|
|
113
|
+
| Channel | Installs |
|
|
114
|
+
| ---------------------------------------------------- | ------------------------------------------------------- |
|
|
115
|
+
| `npm install -D @csark0812/skeleton` | CLI, schemas, audit engine, hook script |
|
|
116
|
+
| `npx skills add csark0812/skeleton --skill skeleton` | `/skeleton` agent skill (ops manual, not the installer) |
|
|
117
|
+
|
|
118
|
+
One command for humans: `npx skeleton init --skills`.
|
|
119
|
+
|
|
120
|
+
## Docs
|
|
121
|
+
|
|
122
|
+
- [Install](docs/developer/install.md)
|
|
123
|
+
- [Doc system](docs/developer/doc-system.md)
|
|
124
|
+
- [Validation](docs/developer/validation.md)
|
|
125
|
+
- [Audit rules](docs/developer/audit.md)
|
|
126
|
+
- [Customize](docs/developer/customize.md)
|
|
127
|
+
- [Authoring conventions](docs/authoring.md)
|
|
128
|
+
|
|
129
|
+
## Development
|
|
130
|
+
|
|
131
|
+
Requires Node ≥ 22. Uses Bun for dev and tests.
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
bun install
|
|
135
|
+
bun test
|
|
136
|
+
bun run build
|
|
137
|
+
bun run audit:self
|
|
138
|
+
```
|