skill-check 0.1.0 → 1.0.0

package/README.md

@@ -4,12 +4,10 @@ Linter for agent skill files — validates SKILL.md files against the spec with
 
 ![skill-check demo](docs/assets/skill-check-demo.gif)
 
-Regenerate with `pnpm run demo:readme` (source: `scripts/readme-demo.tape`).
-
 ## Install
 
 ```bash
-npx skill-check check .
+npx skill-check .
 ```
 
 Global install via curl:
@@ -29,13 +27,15 @@ brew install skill-check
 
 | Command | Description |
 |---|---|
-| `skill-check check [path]` | Run validation (and optional security scan) |
+| `skill-check [path\|github-url]` | Shorthand for `skill-check check [path\|github-url]` |
+| `skill-check check [path\|github-url]` | Run validation (and optional security scan) |
+| `skill-check split-body [path]` | Preview/apply section-based body split into `references/*.md` |
 | `skill-check new <name>` | Scaffold a new skill directory with SKILL.md template |
-| `skill-check watch [path]` | Watch for changes and re-run validation on save |
+| `skill-check watch [path]` | Watch local paths for changes and re-run validation on save |
 | `skill-check diff <a> <b>` | Compare diagnostics between two skill directories |
-| `skill-check report [path]` | Generate a markdown health report |
+| `skill-check report [path\|github-url]` | Generate a markdown health report |
 | `skill-check rules [id]` | List all rules, or show detail for a specific rule |
-| `skill-check security-scan [path]` | Run security scan via agent-scan (mcp-scan) |
+| `skill-check security-scan [path\|github-url]` | Run security scan via agent-scan (mcp-scan) |
 | `skill-check init` | Create `skill-check.config.json` template |
 
 ### check options
@@ -46,8 +46,11 @@ brew install skill-check
 | `--fix --interactive` | Prompt before applying each fix (TTY only) |
 | `--baseline <path>` | Compare against a previous JSON run and show new/fixed counts |
 | `--format <fmt>` | Output format (see below) |
+| `--share` | Render a share card (text format only) |
+| `--share-out <path>` | Save a share image file (default: `./skill-check-share.png`) |
 | `--no-open` | Skip auto-opening HTML reports |
 | `--no-security-scan` | Skip the security scan |
+| `--security-scan-verbose` | Show full raw `agent-scan` output (default is compact summary) |
 | `--strict` | Treat warnings as errors |
 | `--lenient` | Relax selected strict rules |
 | `--fail-on-warning` | Exit non-zero when warnings exist |
@@ -64,9 +67,9 @@ brew install skill-check
 
 **HTML reports** are written to `skill-check-report.html` (or `output.reportPath`). In an interactive terminal the report opens in your browser automatically; use `--no-open` to skip.
 
-**View locally:** `npx skill-check check . --format html` or open the file directly: `open skill-check-report.html` (macOS).
+**View locally:** `npx skill-check . --format html` or open the file directly: `open skill-check-report.html` (macOS).
 
-The `text` formatter includes quality score bars per skill, colorized severity badges, and boxed summaries.
+The `text` formatter includes quality score bars per skill, colorized severity badges, and a share-friendly shield card with the exact runnable `npx skill-check ...` command (including GitHub URL targets when used).
 An ASCII CLI banner is shown in interactive text mode; set `SKILL_CHECK_NO_BANNER=1` to disable it.
 
 ## Quality Scores
@@ -131,18 +134,19 @@ npx skill-check init --interactive
 `skill-check` can validate repos or direct skills directories:
 
 ```bash
-npx skill-check check /path/to/repo
+npx skill-check /path/to/repo
 npx skill-check check ~/.claude/skills
 ```
 
 `check` runs the security scan by default.
-If dependencies are missing, `skill-check` asks before installing in interactive terminals.
-In non-interactive/CI environments, use `--allow-installs` to permit automatic installs.
+If dependencies are missing, `skill-check` automatically installs scanner dependencies by default.
+Use `--no-installs` to hard-block automatic installs.
+By default, `skill-check` prints a compact security summary; use `--security-scan-verbose` for full scanner details.
 
 Run security scan without UV by forcing `pipx`:
 
 ```bash
-npx skill-check security-scan . --security-scan-runner pipx --allow-installs
+npx skill-check security-scan . --security-scan-runner pipx
 ```
 
 Run validation + security scan in one pipeline step with explicit runner:
@@ -193,12 +197,39 @@ Use GitHub annotations in CI:
 npx skill-check check . --format github --no-security-scan
 ```
 
+Generate a screenshot-friendly social summary card:
+
+```bash
+npx skill-check https://github.com/thedaviddias/skill-check --share --no-security-scan
+```
+
+By default this also writes `skill-check-share.png` in your current directory.
+Set a custom output path with `--share-out path/to/card.png`.
+
 Hard-block dependency installs:
 
 ```bash
 npx skill-check check . --no-installs
 ```
 
+## Remote GitHub URLs
+
+`skill-check` supports scanning GitHub repos directly without a manual clone:
+
+```bash
+npx skill-check https://github.com/thedaviddias/skill-check --no-security-scan
+npx skill-check https://github.com/thedaviddias/skill-check/tree/main/skills --no-security-scan
+```
+
+Remote URL scanning behavior:
+
+- Creates an ephemeral shallow clone (`git clone --depth 1`) in a temp directory.
+- Cleans up the checkout automatically after the command finishes.
+- Shows remote preparation progress on stderr (spinner in TTY, `[remote]` status lines in non-TTY/CI).
+- Keeps security scan enabled by default (same as local path behavior).
+- Does not support `--fix` for URL targets (read-only workflow).
+- `watch` and `diff` are local-path only in this version.
+
 ## Auto-fix Coverage
 
 `--fix` currently handles deterministic formatting/metadata issues:
@@ -217,6 +248,30 @@ Rules requiring human intent (content quality, max-length trimming, broken links
 
 Use `--fix --interactive` for per-diagnostic approval prompts (requires TTY).
 
+## Split Oversized Skill Bodies
+
+When `body.max_lines` fails, use `split-body` to extract `##` sections into `references/*.md`.
+
+Preview first (no writes):
+
+```bash
+npx skill-check split-body <skill-dir-or-file>
+```
+
+Apply changes:
+
+```bash
+npx skill-check split-body <skill-dir-or-file> --write
+```
+
+Notes:
+
+- Split is deterministic and section-based (`##` headings).
+- If a long body has no `##` headings, the command reports a blocked plan and explains what to add.
+- `split-body` is local-path only (no GitHub URL mutation flow in v1).
+- After writing, run `npx skill-check check <skill-dir-or-file> --no-security-scan`.
+- For editorial cleanup, use `docs/skills/split-into-references/SKILL.md` or [the published copy](https://github.com/thedaviddias/skill-check/blob/main/docs/skills/split-into-references/SKILL.md).
+
 ## GitHub Action
 
 Use `skill-check` directly in workflows:
@@ -346,7 +401,7 @@ All rules emit actionable `suggestion` text to guide fixes.
 Releases are automated with [semantic-release](https://github.com/semantic-release/semantic-release). Pushing to `main` (after CI passes) runs the release workflow: commits are analyzed for [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `BREAKING CHANGE:`), the version is bumped, `CHANGELOG.md` is updated, the package is published to npm, and a GitHub release is created.
 
 - **Commit messages** are validated locally by [commitlint](https://commitlint.js.org/) (enforced by the `commit-msg` hook). Use `fix:`, `feat:`, `docs:`, `chore:`, etc.
-- **Secrets:** In GitHub, set the `NPM_TOKEN` repository secret (npm automation token with publish scope) so the workflow can publish to npm. `GITHUB_TOKEN` is provided automatically.
+- **npm auth:** Use [npm Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) so you don’t need `NPM_TOKEN`. On [npmjs.com](https://www.npmjs.com/) go to the **skill-check** package → **Settings** → **Trusted publishing** → add a GitHub Actions publisher with workflow filename **`publish.yml`** (exact name, including extension). Then the workflow can publish without any npm token. Alternatively, set the `NPM_TOKEN` repository secret for token-based publish.
 
 To simulate a release locally (without publishing): `pnpm run release:dry-run`. It will fail `verifyConditions` without `NPM_TOKEN` and `GITHUB_TOKEN`; in CI both are set.
 

package/dist/cli/main.d.ts

@@ -2,4 +2,5 @@ export interface CliIO {
     stdout: (text: string) => void;
     stderr: (text: string) => void;
 }
+export declare function normalizeRootCommandArgs(argv: string[]): string[];
 export declare function runCli(argv: string[], io?: CliIO): Promise<number>;