skill-check 0.1.1 → 1.1.0

package/README.md

@@ -4,9 +4,6 @@ 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`).
-The demo runs `npx skill-check .` from repo root and auto-detects skills in tool directories such as `.agents`.
-
 ## Install
 
 ```bash
@@ -30,14 +27,15 @@ brew install skill-check
 
 | Command | Description |
 |---|---|
-| `skill-check [path]` | Shorthand for `skill-check check [path]` |
-| `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
@@ -48,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 |
@@ -68,7 +69,7 @@ brew install skill-check
 
 **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
@@ -140,6 +141,7 @@ npx skill-check check ~/.claude/skills
 `check` runs the security scan by default.
 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`:
 
@@ -195,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:
@@ -219,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:

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>;