@csark0812/skeleton 1.5.1 → 1.5.3
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 +51 -36
- package/dist/cli.js +605 -293
- package/dist/hooks/customize-on-skill-read.js +11 -14
- package/package.json +1 -1
- package/schemas/config.schema.json +22 -0
- package/templates/skeleton-init/config.yaml +6 -0
package/README.md
CHANGED
|
@@ -2,17 +2,25 @@
|
|
|
2
2
|
|
|
3
3
|
**Source of truth for** Package overview.
|
|
4
4
|
|
|
5
|
-
<!-- doc-meta: owner=eng | last-reviewed=2026-07-
|
|
5
|
+
<!-- doc-meta: owner=eng | last-reviewed=2026-07-15 -->
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Agent repos get messy fast. Skills get copied around, docs disagree, links go stale, and nobody remembers which file is actually canonical.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Skeleton is an SSOT linter for that layer. You define the contract once; Skeleton checks it locally and in CI.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
If a canonical doc disappears, a registry drifts, a skill index stops matching disk, or a generated reference gets edited by hand, the audit fails before merge.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Think ESLint, but for the docs and skills your agents rely on.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Skeleton is **not** a runtime agent harness. It doesn't execute tools, enforce permissions, or manage memory. It checks whether the repo around those systems still holds together.
|
|
16
|
+
|
|
17
|
+
## Why this matters
|
|
18
|
+
|
|
19
|
+
Agents can read the repo. They can't reliably infer which of three conflicting docs wins, whether a synced skill should be edited here, or which validation command actually proves a change.
|
|
20
|
+
|
|
21
|
+
That stuff needs to be explicit. More importantly, it needs to stay true after the next 50 PRs.
|
|
22
|
+
|
|
23
|
+
Skeleton turns those repo conventions into checks:
|
|
16
24
|
|
|
17
25
|
| Code repos | Agent repos |
|
|
18
26
|
| ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
@@ -20,7 +28,20 @@ Code has linters. Agent repos need the same thing for docs and SSOT.
|
|
|
20
28
|
| `eslint --fix` on changed files | `skeleton validate changed` on changed docs and skills |
|
|
21
29
|
| Pre-commit + CI gate | `--staged` pre-commit + `--base` CI gate |
|
|
22
30
|
|
|
23
|
-
Skill linters
|
|
31
|
+
Skill linters answer: _"Is this SKILL.md well-formed?"_
|
|
32
|
+
|
|
33
|
+
Skeleton answers the repo-level question: _"Does this whole thing still agree with itself?"_
|
|
34
|
+
|
|
35
|
+
## What the research says
|
|
36
|
+
|
|
37
|
+
Research here is still early, but the direction is useful: more context isn't automatically better.
|
|
38
|
+
|
|
39
|
+
- A [2026 study of repo-level context files](https://doi.org/10.48550/arxiv.2602.11988) tested 438 coding tasks. Human-written files improved resolution by 4% on average; generated files reduced it by 3%. Both increased inference cost by more than 20%. The recommendation was pretty direct: keep instructions minimal and include what the agent can't infer.
|
|
40
|
+
- A [2025 METR randomized trial](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) found experienced open-source developers took 19% longer with early-2025 AI tools while believing they were faster.
|
|
41
|
+
|
|
42
|
+
Neither study proves Skeleton improves task success. That needs a Skeleton-specific benchmark.
|
|
43
|
+
|
|
44
|
+
What they do support is the constraint Skeleton is built around: keep the useful context small, make ownership clear, and verify the rest instead of trusting that it stayed correct.
|
|
24
45
|
|
|
25
46
|
## Quick start
|
|
26
47
|
|
|
@@ -29,7 +50,7 @@ npm install -D @csark0812/skeleton
|
|
|
29
50
|
npx skeleton init --skills
|
|
30
51
|
```
|
|
31
52
|
|
|
32
|
-
|
|
53
|
+
That writes `.skeleton/`, adds the validation scripts, and wires customize hooks for Cursor, Claude Code, and Codex.
|
|
33
54
|
|
|
34
55
|
Edit `.skeleton/config.yaml` for your repo layout, then verify:
|
|
35
56
|
|
|
@@ -37,7 +58,7 @@ Edit `.skeleton/config.yaml` for your repo layout, then verify:
|
|
|
37
58
|
npx skeleton audit self
|
|
38
59
|
```
|
|
39
60
|
|
|
40
|
-
|
|
61
|
+
Flag details: [install](docs/developer/install.md).
|
|
41
62
|
|
|
42
63
|
## What it checks
|
|
43
64
|
|
|
@@ -50,7 +71,7 @@ See [install](docs/developer/install.md) for flags and options.
|
|
|
50
71
|
- **Prose policy** (optional plugins) — YAML pattern rules; idle with no plugins
|
|
51
72
|
- **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
|
|
52
73
|
|
|
53
|
-
|
|
74
|
+
Skeleton doesn't replace your code gates. Keep TypeScript, Python, Nx, pytest, etc. in the repo that owns them.
|
|
54
75
|
|
|
55
76
|
## The `.skeleton/` contract
|
|
56
77
|
|
|
@@ -75,7 +96,7 @@ Register it:
|
|
|
75
96
|
skeleton register docs/developer/api.md
|
|
76
97
|
```
|
|
77
98
|
|
|
78
|
-
Synced
|
|
99
|
+
Synced skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject when the skill is read. No editing copied `SKILL.md` files.
|
|
79
100
|
|
|
80
101
|
## Commands
|
|
81
102
|
|
|
@@ -91,41 +112,33 @@ skeleton customize resolve <slug>
|
|
|
91
112
|
|
|
92
113
|
**Validate changed** routes git diffs to the right audit:
|
|
93
114
|
|
|
94
|
-
| Path | Action
|
|
95
|
-
| ----------------------------------------------------------------------------------- |
|
|
96
|
-
| Docs in scan perimeter | path-scoped audit
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
115
|
+
| Path | Action |
|
|
116
|
+
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
117
|
+
| Docs in scan perimeter | path-scoped audit |
|
|
118
|
+
| Owned skill bodies (`SKILL.md` trees) | exit 1 → run `audit skills` |
|
|
119
|
+
| Foreign / lockfile-synced skill bodies | skip → lint in the owning skills/toolbox repo |
|
|
120
|
+
| `.sh`, `.bash`, `.zsh` | shellcheck or `bash -n` |
|
|
121
|
+
| Other `.json` | JSONC-tolerant syntax check |
|
|
122
|
+
| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `package.json`, `project.json` | skip (exits 1 if all skip) |
|
|
101
123
|
|
|
102
124
|
Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
|
|
125
|
+
|
|
103
126
|
CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
|
|
104
127
|
|
|
105
128
|
## Ecosystem
|
|
106
129
|
|
|
107
|
-
|
|
130
|
+
The model is simple:
|
|
108
131
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
| **
|
|
112
|
-
| **
|
|
113
|
-
| **
|
|
114
|
-
| **Consumer apps** | Call skeleton for SSOT; keep code validation local |
|
|
132
|
+
| Layer | Role |
|
|
133
|
+
| ----------------- | ---------------------------------------------------------------------------------------------- |
|
|
134
|
+
| **Skeleton** | Defines and checks the SSOT contract |
|
|
135
|
+
| **Shared skills** | Reusable team or public skills. [toolbox](https://github.com/csark0812/toolbox) is one example |
|
|
136
|
+
| **Consumer apps** | Pull in the skills, run Skeleton on SSOT paths, and keep their own code gates |
|
|
115
137
|
|
|
116
|
-
Skeleton never calls Nx or
|
|
138
|
+
Skeleton never calls Nx or another app task runner. Consumer repos keep ownership of test, typecheck, and build.
|
|
117
139
|
|
|
118
140
|
See [tiers](docs/tiers.md).
|
|
119
141
|
|
|
120
|
-
## Distribution
|
|
121
|
-
|
|
122
|
-
| Channel | Installs |
|
|
123
|
-
| ---------------------------------------------------- | ------------------------------------------------------- |
|
|
124
|
-
| `npm install -D @csark0812/skeleton` | CLI, schemas, audit engine, hook script |
|
|
125
|
-
| `npx skills add csark0812/skeleton --skill skeleton` | `/skeleton` agent skill (ops manual, not the installer) |
|
|
126
|
-
|
|
127
|
-
One command for humans: `npx skeleton init --skills`.
|
|
128
|
-
|
|
129
142
|
## Docs
|
|
130
143
|
|
|
131
144
|
- [Install](docs/developer/install.md)
|
|
@@ -145,6 +158,8 @@ bun install
|
|
|
145
158
|
bun run check
|
|
146
159
|
```
|
|
147
160
|
|
|
148
|
-
`bun run check`
|
|
161
|
+
`bun run check` = lint + test + typecheck + build + `audit:self`.
|
|
162
|
+
|
|
163
|
+
`validate:changed` is docs/config only for path-scoped work — it skips code/config extensions (see table above). Owned skill-body edits need `audit skills`. All-skip, owned skill paths (alone or mixed with docs), and missing paths exit non-zero. For code: `bun test`, `bun run typecheck`, `bun run build`.
|
|
149
164
|
|
|
150
165
|
Optional: `brew install pre-commit` (or `pipx install pre-commit`), then `pre-commit install` to wire `.pre-commit-config.yaml`.
|