skillgendev 0.1.0__py3-none-any.whl

skillgen/__init__.py

@@ -0,0 +1,7 @@
+"""Compile an app's code into one Agent Skills folder per page."""
+
+# The public name (PyPI package, command, workspace folder) lives here only; everything
+# else derives from it. The import package stays `skillgen` (src/skillgen/).
+TOOL_NAME = "skillgendev"
+
+__version__ = "0.1.0"

skillgen/_data/claude/agents/route-analyzer.md

@@ -0,0 +1,26 @@
+---
+name: {{tool}}-route-analyzer
+description: Analyses one route of a web app for {{tool}}, reading its code read-only and writing the page-analysis JSON. Use one per route when generating several page skills.
+tools: Read, Grep, Glob, Write
+---
+
+You analyse one page of a web application so {{tool}} can write a skill that fills its form.
+
+You receive a route, the path of a prompt file and the path where the analysis must be
+written. Read the prompt file and follow it exactly. Read code only; never edit source
+files. The only file you write is the analysis JSON at the path you were given.
+
+The JSON must match `page-analysis.schema.json` (its path is in the prompt instructions
+you received). Use the app's own words for labels and meanings. Mark every attribute you
+deduced rather than read literally in `inferred`. Never copy real names, emails, numbers
+or IDs from seeds, fixtures or tests.
+
+Find every part of the form that is hidden until something is clicked: wizard steps behind
+Next, tabs, accordion panels, dialogs opened by a button. Follow the state that shows each
+part (a step counter, an active tab, an open flag) to the control that changes it, using
+the imports the prompt's files point to. Describe each part as a view, in the order a
+person fills them, with the click that reaches it from the part before. A field shown
+because another field has a value is `visible_if`, not a view. You describe what to click;
+{{tool}} does the clicking and checks it in a browser.
+
+When done, reply with one line: the route, the number of fields, and any questions.

skillgen/_data/claude/commands/command.md

@@ -0,0 +1,23 @@
+---
+description: Generate Agent Skills that fill this app's forms, one per route. Usage: /{{tool}} /some/route, /{{tool}} all, or /{{tool}} all --name acme
+argument-hint: "/route | all [--name prefix]"
+---
+
+Generate page skills with {{tool}} for: $ARGUMENTS
+
+Follow the `{{tool}}` skill. In short:
+
+1. If `.{{tool}}/config.json` does not exist, run `{{tool}} init` (ask the user for the app's
+   display name and, if they have one, a dev URL).
+2. For `all`: run `{{tool}} routes --all --json`, show the routes, and let the user drop or
+   rename any before generating. For one route, use it as given.
+3. Run `{{tool}} generate --route <route> --json` (or `--all`), passing `--name` through
+   and `--xy` when the user wants x/y.
+4. Follow each result's `next`, as the `{{tool}}` skill says, until nothing is left:
+   `analyse` means you read the prompt and write the analysis yourself (one
+   `{{tool}}-route-analyzer` subagent per route for several); `ask` means you ask the user
+   its question in chat, run `run` on a yes, then run `then`. A result with status
+   `exists` asks before a skill is recreated.
+5. Report each skill folder and any open questions. Ask the user the open questions from
+   `{{tool}} questions --json`, record answers with `{{tool}} answer <id> "<answer>"`, then
+   generate again with `--overwrite`: the user is updating a skill they just made.

skillgen/_data/claude/skills/driver/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: {{tool}}
+description: "Drives the {{tool}} compiler, which turns a web app's code into one Agent Skill per page so Claude can fill that page's form. Use when the user asks to generate, update, check or export page or form skills for their app."
+---
+
+# {{tool}}: generate page skills from an app's code
+
+{{tool}} reads an app's code route by route and writes one skill folder per page
+(`SKILL.md` + `scripts/fill.js`). Anyone can then fill that page in Claude or Cowork with
+the built-in browser, with few tokens. It works for any framework and any app.
+
+## Commands
+- `{{tool}} init [--app-name "Acme"] [--url http://localhost:3000] [--name acme]`
+- `{{tool}} routes --all [--include "admin/*"] [--route /extra] --json`
+- `{{tool}} generate --route /x [--name my-skill] [--overwrite] [--xy [--open STEP]] --json`
+- `{{tool}} generate --all [--name acme] [--overwrite] [--xy] --json`
+- `{{tool}} prepare --route /x --json` → writes the analysis prompt only, without generating.
+- `{{tool}} questions --json`, `{{tool}} answer <id> "<answer>"`
+- `{{tool}} login --url <page>` → opens a browser window; the user signs in and closes it.
+- `{{tool}} add-rule <skill> "<rule>" [--check "key ^A"]`, or `--global`
+- `{{tool}} validate`, `{{tool}} doctor [--fix]`
+- `{{tool}} export [--zip] [--plugin]` → for Claude, Cowork or Claude Code;
+  `{{tool}} export-chatgpt [--zip] [--name acme]` → one ChatGPT plugin.
+
+## Naming
+The user chooses skill names. With one route, `--name` is the exact skill name. With
+`--all`, `--name` is the prefix for every skill (`acme` → `acme-signup`). Names must be
+lowercase letters, digits and single hyphens, at most 64 characters.
+
+## Run, then follow `next` until nothing is left
+{{tool}} never asks on its own; it has no terminal to ask from. When a route cannot
+finish, its result has status `needs` (or `exists`) and a `next` object, and the exit
+code is 3. Do what `next` says, then run its `then` command. Repeat until no result has
+a `next`, or the user says no.
+
+- `"action": "analyse"`: {{tool}} could not run the analysis itself (for example Claude
+  Code is not signed in). Do it yourself: read `prompt` and the files it lists, read-only,
+  following the imports they point to. Write one JSON object matching the schema in the
+  prompt to `write`. Then run `then`; {{tool}} uses your analysis while the code is
+  unchanged. For several routes, use one `{{tool}}-route-analyzer` subagent per route.
+- `"action": "ask"`: only the user can decide or do this. Ask them `ask` in chat, as a
+  question, in your own words if that is clearer.
+  - On yes, run `run` when it is not empty, then run `then`.
+  - `need` `limit`: the AI's own limit is reached and `ask` says when it resets. Tell
+    the user, and stop. Do not read the code and write the analysis yourself: that
+    spends far more of the same limit. Run `then` once the limit has reset; the
+    analysis already done is reused.
+  - `need` `url`: their answer is the address; put it in place of `<url>` in `then`.
+  - `need` `login`: `run` opens a browser window and waits until the user signs in and
+    closes it, so give it a long timeout. Never type their password yourself.
+  - `need` `overwrite`: the skill exists; `then` recreates it. Notes in its user section
+    are kept.
+  - `need` `open`: the form's fields are hidden behind a click. Their answer is the
+    text of the button, tab or link; put it in place of `<label>` in `then`.
+  - `need` `server` or `probe`: the user starts their dev server or reinstalls; wait
+    until they say it is done, then run `then`.
+  - On no, stop that route and say what was left undone.
+
+Answering open questions and generating again is the user updating a skill they made,
+so pass `--overwrite` then.
+
+## Rules
+- Never edit the app's source while analysing.
+- Never copy real personal data or secrets into an analysis or a skill.
+- Facts you deduce go in `inferred`; {{tool}} keeps uncertain facts out of skills until the
+  developer confirms them.
+- When you analyse a page yourself, describe every part hidden until a click (wizard
+  steps, tabs, accordion panels, dialogs) as `views`, in fill order, each with the click
+  that reaches it from the part before; the prompt says how. You never write click code:
+  {{tool}} walks the views in Chromium with `--xy`, measures every field, and the skill
+  walks them the same way when it fills the page.
+- A running app is optional. A normal `generate` reads code only. Add `--xy` to also
+  measure where each field sits (x/y) on the dev copy; it only adds and never removes a
+  field. If the form appears only after a click, add `--route … --open STEP` (a CSS
+  selector or `text:Label`); it is saved, and the skill makes the same click. Dev or
+  staging only; submits are intercepted.

skillgen/_data/hintpacks/README.md

@@ -0,0 +1,85 @@
+# Hint packs
+
+Hint packs are the only place framework knowledge lives. They are YAML data, read by
+generic code; deleting this folder leaves a working tool that finds routes through the
+other sources (your `--route`, the runtime crawl, Claude Code).
+
+Every pack has an `id`, a `kind` and a short `about`. Three kinds exist.
+
+## `kind: folder` — folder-based routing
+
+```yaml
+id: nextjs-app
+kind: folder
+about: Next.js app router (app/**/page.tsx)
+roots: [app, src/app]            # folders to scan, relative to each project root
+requires_any: [next.config.js, package.json]  # files that mark a project root
+page_files: ["page.{tsx,jsx,ts,js,mdx}"]   # file names that make a folder a page
+route_from: folder               # folder: route is the folder path; file: route is the file path
+index_names: [index]             # with route_from: file, these names map to their folder
+skip_segments: ["^\\(.*\\)$", "^@"]       # path parts dropped from the route (groups, slots)
+skip_files: ["^_", "^api$"]      # path parts that make the whole file not a page
+params:                          # how parameter segments are written → :name
+  - "^\\[\\[?\\.\\.\\.(?P<name>\\w+)\\]?\\]$"
+  - "^\\[(?P<name>\\w+)\\]$"
+```
+
+`requires_any` lets one repository hold several apps. Every folder that holds one
+of these files, at any depth, is a project root, and `roots` is looked for inside
+each. In a monorepo with `admin/next.config.js` and `site/package.json`, both
+`admin/src/app` and `site/app` are scanned. Dependency and build folders
+(`node_modules`, `dist`, hidden folders) are never searched. Without `requires_any`
+the pack applies at the repository root only.
+
+## `kind: router` — route declarations found with ast-grep
+
+```yaml
+id: react-router-jsx
+kind: router
+about: <Route path="/x" element={<Page />} />
+language: tsx
+globs: ["**/*.tsx", "**/*.jsx"]
+rule:                            # any ast-grep rule
+  pattern: <Route path=$PATH element={<$COMPONENT $$$ />} $$$ />
+captures:
+  path: PATH                     # metavariable holding the route path (a string literal)
+  component: COMPONENT           # optional: metavariable naming the page component
+prefix_from: none                # reserved for nested routers
+```
+
+The component name is resolved to a file through the code graph, so packs never
+describe import syntax. When the captured text is not a plain name (Rails writes
+`"registrations#new"`), two optional keys reshape it:
+
+```yaml
+component_match: "^[\"']?(?P<name>[\\w/]+)#"   # regex with a `name` group
+component_format: "{pascal}Controller"           # {name} or {pascal}: registrations → RegistrationsController
+```
+
+Shipped router packs: React Router, route objects, Express, Flask, Django, Laravel,
+Rails, Spring MVC, ASP.NET Core attributes and Phoenix. Each has a tiny sample app under
+`tests/fixtures/hintpacks/<id>/` or `tests/fixtures/<app>/`.
+
+When no pack matches, skillgendev asks Claude Code to read the code graph's likely router
+files (`skillgendev routes --all --ask-claude`), so a missing pack never blocks anyone.
+
+## `kind: validator` — field constraints found with ast-grep
+
+```yaml
+id: zod-string-min
+kind: validator
+about: z.string().min(n) inside an object schema
+language: typescript
+rule: { pattern: "$FIELD: z.string().min($MIN)" }
+captures: { field: FIELD, min_length: MIN }
+```
+
+Validator packs only add `EXTRACTED` facts that Claude Code would otherwise read
+itself; they make analysis cheaper, never required.
+
+## Adding a pack
+
+1. Add the YAML file here.
+2. Add a tiny example under `tests/fixtures/hintpacks/<id>/` and a case in
+   `tests/test_hintpacks.py`.
+3. Run `uv run pytest tests/test_hintpacks.py`.

skillgen/_data/hintpacks/folders/astro-pages.yml

@@ -0,0 +1,13 @@
+id: astro-pages
+kind: folder
+about: "Astro src/pages/**/*.astro"
+roots: [src/pages]
+page_files: ["*.astro"]
+route_from: file
+index_names: [index]
+skip_segments: []
+skip_files: ["^_"]
+params:
+  - "^\\[\\.\\.\\.(?P<name>\\w+)\\]$"
+  - "^\\[(?P<name>\\w+)\\]$"
+requires_any: ["astro.config.mjs", "astro.config.ts", "astro.config.js"]

skillgen/_data/hintpacks/folders/nextjs-app.yml

@@ -0,0 +1,13 @@
+id: nextjs-app
+kind: folder
+about: "Next.js app router (app/**/page.tsx)"
+roots: [app, src/app]
+# Where a Next.js project starts, so an app inside a monorepo is found too.
+requires_any: ["next.config.js", "next.config.mjs", "next.config.ts", "package.json"]
+page_files: ["page.tsx", "page.jsx", "page.ts", "page.js", "page.mdx"]
+route_from: folder
+skip_segments: ["^\\(.*\\)$", "^@"]
+skip_files: ["^_", "^api$"]
+params:
+  - "^\\[\\[?\\.\\.\\.(?P<name>\\w+)\\]?\\]$"
+  - "^\\[(?P<name>\\w+)\\]$"

skillgen/_data/hintpacks/folders/nextjs-pages.yml

@@ -0,0 +1,13 @@
+id: nextjs-pages
+kind: folder
+about: "Next.js pages router (pages/**/*.tsx)"
+roots: [pages, src/pages]
+page_files: ["*.tsx", "*.jsx", "*.ts", "*.js", "*.mdx"]
+route_from: file
+index_names: [index]
+skip_segments: []
+skip_files: ["^_", "^api$"]
+params:
+  - "^\\[\\[?\\.\\.\\.(?P<name>\\w+)\\]?\\]$"
+  - "^\\[(?P<name>\\w+)\\]$"
+requires_any: ["next.config.js", "next.config.mjs", "next.config.ts"]

skillgen/_data/hintpacks/folders/nuxt-pages.yml

@@ -0,0 +1,13 @@
+id: nuxt-pages
+kind: folder
+about: "Nuxt pages/ directory (pages/**/*.vue)"
+roots: [pages, app/pages, src/pages]
+page_files: ["*.vue"]
+route_from: file
+index_names: [index]
+skip_segments: ["^\\(.*\\)$"]
+skip_files: ["^_"]
+params:
+  - "^\\[\\.\\.\\.(?P<name>\\w+)\\]$"
+  - "^\\[\\[?(?P<name>\\w+)\\]?\\]$"
+requires_any: ["nuxt.config.ts", "nuxt.config.js"]

skillgen/_data/hintpacks/folders/sveltekit-routes.yml

@@ -0,0 +1,13 @@
+id: sveltekit-routes
+kind: folder
+about: "SvelteKit src/routes/**/+page.svelte"
+roots: [src/routes]
+# Where a SvelteKit project starts, so an app inside a monorepo is found too.
+requires_any: ["svelte.config.js", "svelte.config.ts", "package.json"]
+page_files: ["+page.svelte"]
+route_from: folder
+skip_segments: ["^\\(.*\\)$"]
+skip_files: []
+params:
+  - "^\\[\\[?\\.\\.\\.(?P<name>\\w+)\\]?\\]$"
+  - "^\\[\\[?(?P<name>\\w+)(=\\w+)?\\]?\\]$"

skillgen/_data/hintpacks/routers/aspnet-attributes.yml

@@ -0,0 +1,16 @@
+id: aspnet-attributes
+kind: router
+about: "ASP.NET Core [Route(\"…\")] and [HttpGet(\"…\")] attributes (conventional routes are left to Claude; Razor @page routes come from Graphify)"
+language: csharp
+globs: ["**/*.cs"]
+rule:
+  kind: attribute
+  all:
+    - has: { field: name, regex: "^(HttpGet|Route)$" }
+    - has:
+        kind: attribute_argument_list
+        has:
+          kind: attribute_argument
+          has: { kind: string_literal, pattern: $PATH }
+captures:
+  path: PATH

skillgen/_data/hintpacks/routers/django.yml

@@ -0,0 +1,12 @@
+id: django
+kind: router
+about: "Django path('x/', view) entries in urls.py"
+language: python
+globs: ["**/urls.py"]
+rule:
+  any:
+    - pattern: path($PATH, $VIEW)
+    - pattern: path($PATH, $VIEW, $$$REST)
+captures:
+  path: PATH
+  component: VIEW

skillgen/_data/hintpacks/routers/express.yml

@@ -0,0 +1,9 @@
+id: express
+kind: router
+about: "Express-style app.get('/x', handler) and router.get('/x', handler)"
+language: javascript
+globs: ["**/*.js", "**/*.mjs", "**/*.cjs"]
+rule:
+  pattern: $APP.get($PATH, $$$HANDLERS)
+captures:
+  path: PATH

skillgen/_data/hintpacks/routers/flask.yml

@@ -0,0 +1,21 @@
+id: flask
+kind: router
+about: "Flask-style @app.route('/x') and @blueprint.route('/x') decorators"
+language: python
+globs: ["**/*.py"]
+rule:
+  kind: decorated_definition
+  has:
+    kind: decorator
+    has:
+      any:
+        - pattern: $APP.route($PATH)
+        - pattern: $APP.route($PATH, $$$ARGS)
+        - pattern: $APP.get($PATH)
+  all:
+    - has:
+        field: definition
+        has: { field: name, pattern: $COMPONENT }
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/laravel.yml

@@ -0,0 +1,12 @@
+id: laravel
+kind: router
+about: "Laravel Route::get('/x', [Controller::class, 'action']) and Route::get('/x', ...) declarations"
+language: php
+globs: ["routes/**/*.php"]
+rule:
+  any:
+    - pattern: "Route::get($PATH, [$COMPONENT::class, $ACTION])"
+    - pattern: "Route::get($PATH, $$$REST)"
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/phoenix.yml

@@ -0,0 +1,13 @@
+id: phoenix
+kind: router
+about: "Phoenix router: get \"/signup\", SignupController, :new and live \"/contact\", ContactLive"
+language: elixir
+globs: ["**/router.ex", "**/*_router.ex"]
+rule:
+  any:
+    - pattern: "get $PATH, $COMPONENT, $ACTION"
+    - pattern: "live $PATH, $COMPONENT"
+    - pattern: "live $PATH, $COMPONENT, $ACTION"
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/rails.yml

@@ -0,0 +1,14 @@
+id: rails
+kind: router
+about: "Rails routes.rb: get \"/signup\", to: \"registrations#new\" (resources blocks are left to Claude)"
+language: ruby
+globs: ["config/routes.rb", "config/routes/**/*.rb"]
+rule:
+  any:
+    - pattern: "get $PATH, to: $COMPONENT"
+    - pattern: "get $PATH, to: $COMPONENT, $$$REST"
+captures:
+  path: PATH
+  component: COMPONENT
+component_match: "^[\"']?(?P<name>[\\w/]+)#"
+component_format: "{pascal}Controller"

skillgen/_data/hintpacks/routers/react-router-jsx.yml

@@ -0,0 +1,13 @@
+id: react-router-jsx
+kind: router
+about: "React Router JSX routes, <Route path=\"/x\" element={<Page />} />"
+language: tsx
+globs: ["**/*.tsx", "**/*.jsx"]
+rule:
+  pattern: <Route path="$PATH" $$$ATTRIBUTES />
+  has:
+    pattern: <$COMPONENT $$$PROPS />
+    stopBy: end
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/route-objects-js.yml

@@ -0,0 +1,21 @@
+id: route-objects-js
+kind: router
+about: "Route objects in JavaScript files, such as { path: '/x', component: Page } (Vue Router, React Router data routers)"
+language: javascript
+globs: ["**/*.js", "**/*.mjs", "**/*.cjs"]
+rule:
+  kind: object
+  all:
+    - has:
+        kind: pair
+        all:
+          - has: { field: key, regex: "^path$" }
+          - has: { field: value, pattern: $PATH }
+    - has:
+        kind: pair
+        all:
+          - has: { field: key, regex: "^(component|element)$" }
+          - has: { field: value, pattern: $COMPONENT }
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/route-objects.yml

@@ -0,0 +1,21 @@
+id: route-objects
+kind: router
+about: "Route objects such as { path: '/x', component: Page } (Vue Router, Angular, React Router data routers)"
+language: typescript
+globs: ["**/*.ts", "**/*.mts", "**/*.cts"]
+rule:
+  kind: object
+  all:
+    - has:
+        kind: pair
+        all:
+          - has: { field: key, regex: "^path$" }
+          - has: { field: value, pattern: $PATH }
+    - has:
+        kind: pair
+        all:
+          - has: { field: key, regex: "^(component|element)$" }
+          - has: { field: value, pattern: $COMPONENT }
+captures:
+  path: PATH
+  component: COMPONENT

skillgen/_data/hintpacks/routers/spring.yml

@@ -0,0 +1,13 @@
+id: spring
+kind: router
+about: "Spring MVC @GetMapping(\"/signup\") and @RequestMapping(\"/signup\") on controller methods"
+language: java
+globs: ["**/*.java", "**/*.kt"]
+rule:
+  any:
+    - pattern: "@GetMapping($PATH)"
+    - pattern: "@GetMapping(value = $PATH)"
+    - pattern: "@GetMapping(path = $PATH)"
+    - pattern: "@RequestMapping($PATH)"
+captures:
+  path: PATH

skillgen/analyze/__init__.py

@@ -0,0 +1 @@
+"""The analysis step: prompts, the page-analysis schema, and runners."""