frontend-assessment-skill 1.0.0 → 1.0.8

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.
Files changed (3) hide show
  1. package/README.md +2 -41
  2. package/package.json +2 -6
  3. package/skills/SKILL.md +106 -68
package/README.md CHANGED
@@ -54,48 +54,9 @@ The skill calculates a strict, reproducible score (0–100) across 7 criteria:
54
54
 
55
55
  ---
56
56
 
57
- ## Development & Publishing
57
+ ## Contributing
58
58
 
59
- ### 1. Local Testing
60
-
61
- To test the CLI installer locally before publishing:
62
-
63
- ```bash
64
- # Test help output
65
- node bin/cli.js --help
66
-
67
- # Test interactive installation
68
- node bin/cli.js
69
-
70
- # Test npx invocation locally in the package root
71
- npx .
72
- ```
73
-
74
- ### 2. Versioning & Git Setup
75
-
76
- Initialize your git repository and prepare a release:
77
-
78
- ```bash
79
- git init
80
- git add .
81
- git commit -m "Initial release of frontend-assessment-skill"
82
- ```
83
-
84
- ### 3. Publishing to npm (via GitHub Actions)
85
-
86
- This repository includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically publishes to npm when a GitHub Release is published, with support for npm provenance.
87
-
88
- 1. Create an **Access Token** on [npmjs.com](https://www.npmjs.com) (Automation token or Granular Access Token with Read and write access to packages).
89
- 2. Add it as a secret in your GitHub repository:
90
- - Navigate to **Settings > Secrets and variables > Actions**
91
- - Create a new repository secret named `NPM_TOKEN` with your npm token value.
92
- 3. To publish a release:
93
- - Update `version` in `package.json` (e.g. `npm version patch`)
94
- - Push commits and tags to GitHub
95
- - Create and publish a new Release in GitHub (e.g. `v1.0.0`)
96
- - The workflow will automatically publish the package with npm provenance enabled.
97
-
98
- Alternatively, you can manually trigger the workflow from the **Actions** tab in GitHub.
59
+ Contributions are welcome! Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for local development setup, testing instructions, and the release workflow.
99
60
 
100
61
  ---
101
62
 
package/package.json CHANGED
@@ -1,13 +1,9 @@
1
1
  {
2
2
  "name": "frontend-assessment-skill",
3
- "version": "1.0.0",
3
+ "version": "1.0.8",
4
4
  "description": "Installer for the frontend-assessment agent skill (Zed, Claude, and agent tools)",
5
5
  "type": "module",
6
- "main": "bin/cli.js",
7
- "bin": {
8
- "frontend-assessment-skill": "./bin/cli.js",
9
- "frontend-assessment": "./bin/cli.js"
10
- },
6
+ "bin": "./bin/cli.js",
11
7
  "files": [
12
8
  "bin",
13
9
  "skills",
package/skills/SKILL.md CHANGED
@@ -1,10 +1,9 @@
1
1
  ---
2
-
3
2
  name: frontend-assessment
4
3
 
5
4
  description: Assess frontend health and maturity. USE WHEN the user asks for a "frontend assessment", "frontend health check", "frontend review", "frontend score", or wants a reproducible 1-100 score for dependency freshness, core package currency, contributor activity, delivery cadence, testing, coverage, and UI system & component library adoption.
6
-
7
5
  ---
6
+
8
7
  ---
9
8
 
10
9
  # Frontend Assessment
@@ -29,31 +28,31 @@ Measure frontend health in a way that is:
29
28
  ## Assessment Scope
30
29
 
31
30
  1. Identify the frontend surface being assessed.
32
- - In a monorepo, prefer the primary deployable frontend application(s).
33
- - If the repo contains multiple frontend apps and the user did not narrow scope, assess the main production-facing app(s) plus shared frontend libraries used by them.
34
- - State the scope explicitly in the report.
31
+ - In a monorepo, prefer the primary deployable frontend application(s).
32
+ - If the repo contains multiple frontend apps and the user did not narrow scope, assess the main production-facing app(s) plus shared frontend libraries used by them.
33
+ - State the scope explicitly in the report.
35
34
  2. Detect the package manager from lockfiles and use the workspace-native tooling.
36
35
  3. Prefer direct evidence from:
37
- - `package.json` and relevant app/library manifests
38
- - lockfiles
39
- - build/test/project configuration
40
- - git history
41
- - GitHub releases / PR metadata
42
- - UI system and design token package manifests & deprecation metadata
36
+ - `package.json` and relevant app/library manifests
37
+ - lockfiles
38
+ - build/test/project configuration
39
+ - git history
40
+ - GitHub releases / PR metadata
41
+ - UI system and design token package manifests & deprecation metadata
43
42
 
44
43
  ## Stack Detection
45
44
 
46
45
  Detect the frontend stack first. Typical examples:
47
46
 
48
- | Category | Candidate packages |
49
- | --- | --- |
50
- | UI runtime | `react`, `vue`, `angular`, `svelte` |
51
- | App framework | `next`, `remix`, `@remix-run/*`, `gatsby`, `nuxt` |
52
- | Router | `react-router`, `react-router-dom`, `@tanstack/router`, framework router |
53
- | Build tool | `vite`, `webpack`, `rspack`, `parcel` |
54
- | Test tools | `jest`, `vitest`, `cypress`, `playwright` |
55
- | UI component library | `@mui/*`, `@chakra-ui/*`, `antd`, `@mantine/*`, `@radix-ui/*`, `shadcn` (`components.json`), `@carbon/*`, `@fluentui/*`, `react-bootstrap`, `@shoelace-style/*`, in-house/custom design system |
56
- | Design tokens / Styling | `style-dictionary`, `@tokens-studio/*`, design token packages, `tailwindcss`, `@vanilla-extract/*`, `styled-components`, `@emotion/*`, CSS variables/theme tokens |
47
+ | Category | Candidate packages |
48
+ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
+ | UI runtime | `react`, `vue`, `angular`, `svelte` |
50
+ | App framework | `next`, `remix`, `@remix-run/*`, `gatsby`, `nuxt` |
51
+ | Router | `react-router`, `react-router-dom`, `@tanstack/router`, framework router |
52
+ | Build tool | `vite`, `webpack`, `rspack`, `parcel` |
53
+ | Test tools | `jest`, `vitest`, `cypress`, `playwright` |
54
+ | UI component library | `@mui/*`, `@chakra-ui/*`, `antd`, `@mantine/*`, `@radix-ui/*`, `shadcn` (`components.json`), `@carbon/*`, `@fluentui/*`, `react-bootstrap`, `@shoelace-style/*`, in-house/custom design system |
55
+ | Design tokens / Styling | `style-dictionary`, `@tokens-studio/*`, design token packages, `tailwindcss`, `@vanilla-extract/*`, `styled-components`, `@emotion/*`, CSS variables/theme tokens |
57
56
 
58
57
  When a stack-specific package from the user's examples is not present, substitute the equivalent core package(s) for that stack.
59
58
 
@@ -102,17 +101,17 @@ Useful evidence sources:
102
101
 
103
102
  ### 3. Contributor activity
104
103
 
105
- Count unique contributors in the last 12 months from git history. Prefer:
104
+ First determine whether the available git history spans at least three months by checking the oldest reachable commit (for example, `git log --all --format=%cI | sort | sed -n '1p'`) and whether the checkout is shallow (`git rev-parse --is-shallow-repository`). If it does, count unique contributors over the last three months:
106
105
 
107
106
  ```bash
108
- git log --since="12 months ago" --format='%aN <%aE>' --all | sort -u
107
+ git log --since="3 months ago" --format='%aN <%aE>' --all | sort -u
109
108
  ```
110
109
 
111
- Use the unique author list count as the metric. This is a diversity signal, not a popularity contest.
110
+ Use the unique author list count as the metric. This is a diversity signal, not a popularity contest. If the repository has less than three months of available history, or a shallow clone prevents confirming the history span, mark this criterion `N/A` rather than treating missing history as zero contributors.
112
111
 
113
- ### 4. Quarterly delivery cadence
112
+ ### 4. Three-month delivery cadence
114
113
 
115
- For the assessed quarter, count:
114
+ For the last three months, count:
116
115
 
117
116
  - commits
118
117
  - merges
@@ -121,12 +120,12 @@ For the assessed quarter, count:
121
120
  Prefer:
122
121
 
123
122
  ```bash
124
- git rev-list --count --since="<quarter-start>" --until="<quarter-end>" --all
125
- git rev-list --count --merges --since="<quarter-start>" --until="<quarter-end>" --all
123
+ git rev-list --count --since="3 months ago" --all
124
+ git rev-list --count --merges --since="3 months ago" --all
126
125
  gh api repos/<owner>/<repo>/releases --paginate
127
126
  ```
128
127
 
129
- Use GitHub Releases where available. If there are no GitHub releases, record `0` and note if the repo appears to release by tags or another mechanism.
128
+ Use GitHub Releases in the same three-month window where available. If there are no GitHub releases, record `0` and note if the repo appears to release by tags or another mechanism. If the repository has less than three months of available history, or a shallow clone prevents confirming the history span, mark this criterion `N/A` rather than treating unavailable history as zero activity.
130
129
 
131
130
  ### 5. Test suites
132
131
 
@@ -157,23 +156,34 @@ Inspect the project dependencies and source code to identify and assess:
157
156
 
158
157
  - **Detected component libraries**: Name all UI component libraries in use (e.g. `@mui/*`, `antd`, `@chakra-ui/*`, `@mantine/*`, `@radix-ui/*`, `shadcn`, `@carbon/*`, `@fluentui/*`, `react-bootstrap`, in-house component library, etc.).
159
158
  - **Detected design tokens / theme libraries**: Identify design token packages and formal theme tokens (e.g. `style-dictionary`, `@tokens-studio/*`, dedicated token packages, CSS variables/theme definitions).
160
- - **Consistency**: Verify whether a **single component library** is used consistently across the application, or if multiple competing UI libraries are mixed.
159
+ - **Detected styling approach**: Inspect the source for CSS-in-JS usage—styling authored in JavaScript or JSX, such as style objects, tagged-template styles, or styling expressions—and note whether it is runtime-generated or compiled where evident. Treat CSS-in-JS as a coding approach, not a package category.
160
+ - **Consistency**: Verify whether a **single component library** is used consistently across the application and whether the styling approach is consistent, or if multiple competing UI libraries or styling systems are mixed.
161
161
  - **Deprecation check**: Check if any detected UI library or token package is deprecated using `npm view <package> deprecated --json` or known deprecation status.
162
162
  - **Adoption & version currency**: Evaluate if the component library and design system are actively used across the app and on supported versions.
163
163
 
164
164
  ## Scoring Rubric
165
165
 
166
- Score each criterion independently and sum to **100**.
166
+ Score each applicable criterion independently. When at least three months of history are available, score all criteria and sum to **100**. If less than three months of history are available (or a shallow clone prevents verifying the span), mark both history-based criteria as `N/A`, do not score them as zero, and exclude their combined 20 points from the denominator. Normalize the earned points against the remaining applicable maximum to produce a score out of 100, and report both the raw earned/available points and normalized score.
167
+
168
+ | Criterion | Weight | How to score |
169
+ | ---------------------------------------- | -----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
+ | Dependency freshness | 20 | `score = round(20 * fresh_ratio)` where `fresh_ratio` is the share of assessed packages that are both on latest version **or** at most one minor behind **and** whose installed version is not older than 183 days. If a package has had no release in the last 183 days at all, treat it as neutral rather than stale if the installed version is latest. |
171
+ | Core package currency | 20 | `20` all core packages latest or latest compatible and blockers are documented; `15` only minor lag or documented peer/framework blockers; `8` one core package is one major behind without blocker; `0` multiple core packages are one major behind or any core package is more than one major behind without blocker. |
172
+ | Contributors, last 3 months | 10 | `10` >= 4 contributors; `8` 3 contributors; `6` 2 contributors; `3` 1 contributor; `0` 0 contributors. Cap at 10 so very large teams do not dominate the score. If available history is shorter than three months or cannot be verified, mark `N/A` and exclude this weight from the score denominator. |
173
+ | Last 3 months: commits, merges, releases | 10 | Score three sub-parts and add them: commits `0-4` (`>=50` = 4, `20-49` = 3, `5-19` = 2, `1-4` = 1, `0` = 0), merges `0-3` (`>=15` = 3, `5-14` = 2, `1-4` = 1, `0` = 0), releases `0-3` (`>=2` = 3, `1` = 2, `0` = 0). If available history is shorter than three months or cannot be verified, mark `N/A` and exclude this weight from the score denominator. |
174
+ | Test suite maturity | 10 | `10` unit plus integration/e2e/component coverage across meaningful app flows; `7` at least two test layers; `4` one automated test layer only; `0` no automated tests found. |
175
+ | Coverage | 10 | `10` >= 80%; `8` 70-79%; `6` 60-69%; `3` 40-59%; `1` 1-39%; `0` no measurable coverage found. Use the most relevant frontend coverage number, not backend-only coverage. |
176
+ | UI system & component library | 20 | Assess the component library, tokens/theme, and styling approach (including CSS-in-JS) together. `20` single modern component library used consistently with formal design tokens and a maintained, consistent styling approach; `15` single component library used consistently with design tokens/theme and a maintained styling approach (minor lag or isolated deviations); `10` single component library without formal tokens OR custom design system without token library; `5` mixed/competing component libraries or styling approaches (fragmented UI) OR deprecated library with migration underway; `0` deprecated/unmaintained UI library as primary UI, severe library fragmentation, or no component library/tokens. CSS-in-JS use alone does not increase the score; assess its consistency, maintenance status, and integration with the UI system. |
177
+
178
+ ## Repository Context Rubric
167
179
 
168
- | Criterion | Weight | How to score |
169
- | ----------------------------------- | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
- | Dependency freshness | 20 | `score = round(20 * fresh_ratio)` where `fresh_ratio` is the share of assessed packages that are both on latest version **or** at most one minor behind **and** whose installed version is not older than 183 days. If a package has had no release in the last 183 days at all, treat it as neutral rather than stale if the installed version is latest. |
171
- | Core package currency | 20 | `20` all core packages latest or latest compatible and blockers are documented; `15` only minor lag or documented peer/framework blockers; `8` one core package is one major behind without blocker; `0` multiple core packages are one major behind or any core package is more than one major behind without blocker. |
172
- | Contributors, last 12 months | 10 | `10` >= 4 contributors; `8` 3 contributors; `6` 2 contributors; `3` 1 contributor; `0` 0 contributors. Cap at 10 so very large teams do not dominate the score. |
173
- | Quarterly commits, merges, releases | 10 | Score three sub-parts and add them: commits `0-4` (`>=50` = 4, `20-49` = 3, `5-19` = 2, `1-4` = 1, `0` = 0), merges `0-3` (`>=15` = 3, `5-14` = 2, `1-4` = 1, `0` = 0), releases `0-3` (`>=2` = 3, `1` = 2, `0` = 0). |
174
- | Test suite maturity | 10 | `10` unit plus integration/e2e/component coverage across meaningful app flows; `7` at least two test layers; `4` one automated test layer only; `0` no automated tests found. |
175
- | Coverage | 10 | `10` >= 80%; `8` 70-79%; `6` 60-69%; `3` 40-59%; `1` 1-39%; `0` no measurable coverage found. Use the most relevant frontend coverage number, not backend-only coverage. |
176
- | UI system & component library | 20 | `20` single modern component library used consistently across the app + formal design system & token library adoption, non-deprecated; `15` single component library used consistently with design tokens/theme system (minor version lag or isolated deviations); `10` single component library without formal tokens OR custom design system without token library; `5` mixed/competing component libraries (fragmented UI) OR deprecated library with migration underway; `0` deprecated/unmaintained UI library as primary UI, severe library fragmentation, or no component library/tokens. |
180
+ Report this context score separately. **Do not add it to or subtract it from the 100-point frontend assessment score.**
181
+
182
+ | Context factor | Points | How to score |
183
+ | ------------------- | -----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
184
+ | Repository age | 0-3 | `0` < 3 months old; `1` 3-11 months; `2` 1-2 years; `3` >= 3 years. Use first commit date. |
185
+ | Frontend complexity | 0-4 | `0` no clear frontend app; `1` exactly one frontend app/package and no shared frontend packages; `2` one deployable frontend app plus one or more shared frontend packages; `3` two or more frontend apps or a monorepo frontend workspace; `4` two or more deployable frontend apps plus shared frontend libraries or a design system package. |
186
+ | Active developers | 0-3 | `0` 0 active contributors in last 12 months; `1` 1; `2` 2-3; `3` >= 4. Use the same contributor count as the main rubric. |
177
187
 
178
188
  ## Important Scoring Rules
179
189
 
@@ -183,7 +193,7 @@ Score each criterion independently and sum to **100**.
183
193
  4. **Penalize deprecated and fragmented UI libraries.** Using deprecated UI packages or mixing multiple competing component libraries directly reduces the UI system score.
184
194
  5. **Reward consistent single component library and design token usage.** Full points require a single unified component library paired with a design system and token library.
185
195
  6. **Keep the rubric fixed.** If you must diverge, explain exactly why.
186
- 7. **Factor in when calculating the score** the age of the repository, complexity and number of developers active in the repo.
196
+ 7. **Do not use repository age, complexity, or team size to adjust the 100-point score.** Report them only in the separate repository context rubric.
187
197
 
188
198
  ## Required Output
189
199
 
@@ -192,58 +202,84 @@ Return the assessment in this structure:
192
202
  ### Scope
193
203
 
194
204
  - repository / app(s) assessed
195
- - quarter assessed
205
+ - assessment window (last three months)
196
206
  - detected stack
207
+ - model(s) used to run the assessment; use the agent/model name if available, otherwise `Unknown`
197
208
  - detected UI system & component library: `<names of detected libraries or "None">`
198
209
  - detected design tokens / theme library: `<names of detected token packages or "None">`
210
+ - detected styling approach, including any CSS-in-JS usage in JavaScript/JSX: `<brief description, or "None detected">`
199
211
 
200
212
  ### Score summary
201
213
 
202
214
  `Frontend assessment score: <total>/100`
203
215
 
216
+ If history-based criteria are `N/A`, also report the raw score and applicable maximum, for example: `Frontend assessment score: 90/100 (72/80 applicable points)`.
217
+
204
218
  ### Scoring table
205
219
 
206
- | Criterion | Weight | Evidence | Score | Notes |
207
- | --- | ---: | --- | ---: | --- |
208
- | Dependency freshness | 20 | ... | ... | ... |
209
- | Core package currency | 20 | ... | ... | ... |
210
- | Contributors, last 12 months | 10 | ... | ... | ... |
211
- | Quarterly commits, merges, releases | 10 | ... | ... | ... |
212
- | Test suite maturity | 10 | ... | ... | ... |
213
- | Coverage | 10 | ... | ... | ... |
214
- | UI system & component library | 20 | ... (Names of used component libraries & token libraries, consistency status, and deprecation status) | ... | ... |
215
- | **Total** | **100** | | **<total>** | |
220
+ | Criterion | Weight | Evidence | Score | Model(s) used | Notes |
221
+ | ---------------------------------------- | ------------------------------: | ----------------------------------------------------------------------------------------------------- | -------------------------: | ------------- | ----- |
222
+ | Dependency freshness | 20 | ... | ... | ... | ... |
223
+ | Core package currency | 20 | ... | ... | ... | ... |
224
+ | Contributors, last 3 months | 10 | ... | ... | ... | ... |
225
+ | Last 3 months: commits, merges, releases | 10 | ... | ... | ... | ... |
226
+ | Test suite maturity | 10 | ... | ... | ... | ... |
227
+ | Coverage | 10 | ... | ... | ... | ... |
228
+ | UI system & component library | 20 | ... (Names of used component libraries & token libraries, consistency status, and deprecation status) | ... | ... | ... |
229
+ | **Total** | **100** (or applicable maximum) | ... raw earned/applicable points | **<normalized total>/100** | | ... |
230
+
231
+ ### Repository context score
232
+
233
+ Report this separate context rubric. It must not affect the frontend assessment score:
234
+
235
+ | Context factor | Evidence | Score |
236
+ | ----------------------- | ----------------------------------------- | -------------: |
237
+ | Repository age | ... | ... |
238
+ | Frontend complexity | ... | ... |
239
+ | Active developers | ... | ... |
240
+ | **Total context score** | Not included in frontend assessment score | **<total>/10** |
216
241
 
217
242
  ### UI system & component library status
218
243
 
219
- Include a breakdown of detected UI and design token packages:
244
+ Include a breakdown of detected UI component library and design token packages. Describe styling approaches—including any CSS-in-JS usage found in JavaScript/JSX—separately; do not report CSS-in-JS itself as a package.
220
245
 
221
246
  | Library / Package | Role (Component library / Tokens / Styling) | Installed version | Latest version | Deprecated? | Consistency & Notes |
222
- | --- | --- | --- | --- | --- | --- |
247
+ | ----------------- | ------------------------------------------- | ----------------- | -------------- | ----------- | ------------------- |
223
248
 
224
249
  ### Core package status
225
250
 
226
251
  Include a compact table for the detected core packages:
227
252
 
228
253
  | Package | Current | Latest | Status | Blocked by dependency? |
229
- | --- | --- | --- | --- | --- |
254
+ | ------- | ------- | ------ | ------ | ---------------------- |
255
+
256
+ ### Top 5 pros
257
+
258
+ List the five strongest pros in ranked order:
259
+
260
+ 1. ...
261
+ 2. ...
262
+ 3. ...
263
+ 4. ...
264
+ 5. ...
230
265
 
231
- ### Top 10 pros and cons
266
+ ### Top 5 cons
232
267
 
233
- Use exactly 10 ranked rows:
268
+ List the five most significant cons in ranked order:
234
269
 
235
- | Rank | Pro | Con |
236
- | ---: | --- | --- |
237
- | 1 | ... | ... |
238
- | 2 | ... | ... |
239
- | 3 | ... | ... |
240
- | 4 | ... | ... |
241
- | 5 | ... | ... |
242
- | 6 | ... | ... |
243
- | 7 | ... | ... |
244
- | 8 | ... | ... |
245
- | 9 | ... | ... |
246
- | 10 | ... | ... |
270
+ 1. ...
271
+ 2. ...
272
+ 3. ...
273
+ 4. ...
274
+ 5. ...
275
+
276
+ ### Frontend business logic diagram
277
+
278
+ Include a low-level Mermaid `flowchart` tracing the main frontend business flows from routes/pages and user actions through relevant components, state management, domain/business logic, and API/data-access layers to their data sources and endpoints. Show meaningful request/response or state transitions where they are evident from the code.
279
+
280
+ - Inspect the frontend source, routing, state/data-fetching code, API clients, and configuration; represent only verified flows and label unknowns rather than inventing behavior.
281
+ - Include backend services and other dependencies that are outside the assessed frontend code. For a monorepo, distinguish services/packages found elsewhere in the repository from services hosted outside the repository. Show external API/service endpoint names or URLs when discoverable; if configured via an environment variable, show the variable name (never its secret value) and mark the destination unresolved if necessary.
282
+ - Keep the diagram focused on business logic and data flow rather than a generic infrastructure overview. Use Mermaid syntax in a fenced `mermaid` block.
247
283
 
248
284
  ### Verdict
249
285
 
@@ -252,6 +288,8 @@ End with:
252
288
  - one short paragraph explaining what drove the score
253
289
  - one short paragraph naming the highest-leverage improvements
254
290
 
291
+ If either history-based criterion is `N/A`, do not cite the overall score as being driven by contribution or delivery-cadence factors, and do not discuss those factors in the verdict. Base the verdict only on the scored criteria and note the unavailable history outside the verdict (in the scope or scoring table).
292
+
255
293
  ## Behavior Notes
256
294
 
257
295
  - Prefer repository-native commands and existing CI/test scripts.