Add skilldeck new and skilldeck validate for skill authors

CHANGELOG.md

@@ -473,6 +473,43 @@ All notable changes to this project are documented here. The format is based on
 
 ### Added
 
+- Skill author commands (#72). `skilldeck new NAME --category ...` scaffolds
+  a skill: a `meta.yaml` with every required field (version `0.1.0`, every
+  agent unless `--agent` narrows it, and the read-only review `capabilities`
+  the bundled review skills declare: read the repository, `git fetch`,
+  `git diff` and `git ls-files`, and the git remote) and a `skill.md`
+  skeleton with the shared review-skill structure (Scope diff steps, finding
+  format, the severity rubric word for word, verify-before-reporting,
+  findings cap, report header). Wherever domain content goes it writes a
+  `TODO(author)` placeholder; it states no domain guidance and cites no
+  source. In a checkout it also scaffolds `evals/fixtures/NAME/` (skip with
+  `--no-eval-fixture`). `skilldeck validate [NAME|PATH]... [--skills-dir]
+  [--json]` checks skills offline: metadata and the capability declaration,
+  the bundle rules (links, directories, undeclared executables and other
+  files, each reported and never followed), structure, cited sources and
+  local links, declared commands against the body's code spans, leftover
+  placeholders, rendering by every adapter (legacy formats included) and the
+  catalog entry; in a checkout also the eval fixtures (loaded through
+  `evals/run_evals.py`: layout, keywords that echo the planted code, a
+  clean-diff fixture's tolerance), the skill's row in
+  `docs/finding-output.md`, and generated-output freshness
+  (`scripts/build_plugin.py --check`, in process). It never runs code from
+  the tree it checks: the checks that import a checkout's scripts run only
+  when that checkout's `src/skilldeck` is the running skilldeck, and are
+  reported as skipped otherwise. Each problem names the file and line, a
+  rule id, and a fix; `--json` is deterministic, and the exit status is 0
+  only when clean. A fresh skeleton passes every metadata, capability and
+  structure check and is rated `incomplete` (not `invalid`) until its
+  placeholders, sources and eval fixture are written. Outside a checkout
+  both commands need an explicit directory (`--dir`, `--skills-dir`), for
+  organization skills, and `new` never writes into the installed package.
+  `docs/authoring-skills.md` now leads with the commands, lists every rule,
+  and documents the review path for official and organization skills. The
+  structure, citation and declared-command rules moved from the tests into
+  `skilldeck.lint`, which the tests and `validate` share, and the registry's
+  errors carry the rule they break (and, for a YAML syntax error, its line).
+  The fixture keyword-echo and clean-tolerance checks moved into
+  `evals/run_evals.py` helpers that the fixture tests and `validate` share.
 - Lifecycle and compatibility policy, `docs/lifecycle.md` (#78), linked from
   the README, `CONTRIBUTING.md`, `docs/releasing.md`,
   `docs/authoring-skills.md`, `docs/compatibility.md` and `docs/catalog.md`.

CLAUDE.md

@@ -49,19 +49,38 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   `skill.md`); inside the package so they're bundled into the wheel
 - `src/skilldeck/` — the installer package
   - `cli.py` — `skilldeck list/show/install/uninstall/status/update/migrate`,
-    `provenance` and `catalog`
+    `provenance`, `catalog`, and the author commands `new` and `validate`
   - `registry.py` — discovers and validates skills, including the optional
     `deprecated` metadata, and the bundle rules: a skill directory is exactly
     regular `meta.yaml` + `skill.md` (no scripts, assets, symlinks or
     junctions; OS/editor leftovers such as `.DS_Store` are ignored when
     loading but still fail `provenance --verify`), and `skill.md` links only
-    to the web or its own headings
+    to the web or its own headings. Each `SkillError` for a malformed skill
+    carries its `validate` rule id
   - `capabilities.py` — the versioned `capabilities` declaration every
     `meta.yaml` carries (files, commands, network, credentials, tools,
     artifacts), its validation, the `## Declared capabilities` notice
     adapters append for skills that ask for more than a read-only review
     (reading files plus read-only git commands; those render unchanged), and
     the summary `show --summary` / `install --dry-run` print
+  - `lint.py` — the one home of the skill rules (skill-directory bundle,
+    structural template, severity rubric copy, citation hygiene, declared
+    commands vs code spans, placeholders) and the `RULES` table of every
+    `validate` rule id, level and remediation; `tests/test_skill_structure.py`
+    and `test_skill_citations.py` apply the same functions to the bundled
+    skills. Add a rule here and to the rules table in
+    `docs/authoring-skills.md` (a test compares them)
+  - `authoring.py` — `skilldeck new` (scaffold with the read-only review
+    capability baseline, `TODO(author)` placeholders, no domain guidance) and
+    `skilldeck validate` (per-skill checks plus, in a checkout's
+    `src/skilldeck/skills`, eval fixtures, `docs/finding-output.md` and
+    generated-output freshness via the checkout's own `evals/run_evals.py`
+    and `scripts/build_plugin.py`, imported in process). Outside a checkout it
+    needs an explicit `--dir`/`--skills-dir` and never writes into the
+    installed package. `validate` never runs code from the tree it checks:
+    the script-importing checks run only when the checkout's `src/skilldeck`
+    is the running package (`_trusted_checkout`), else they are reported as
+    skipped; links in a skill are reported, never read
   - `catalog.py` + `catalog.schema.json` — the public, schema-versioned
     `skilldeck catalog --json` contract (the schema ships in the wheel);
     change it only per the compatibility rules in `docs/catalog.md` (bump
@@ -133,16 +152,18 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   are maintained by hand (see `docs/compatibility.md#contract-tests`). Only
   state vendor behaviour a primary source confirms; mark the rest
   *unverified*.
-- New skills follow the structural template (enforced by
-  `tests/test_skill_structure.py`), ground their checklists in **fetched**
-  authoritative sources (OWASP/CIS/vendor docs) cited in the skill body, and
-  land with a golden-diff eval fixture under `evals/fixtures/` (ideally also a
-  `-clean` one).
+- New skills start from `skilldeck new`, follow the structural template
+  (the `skilldeck.lint` rules, which `skilldeck validate` reports and
+  `tests/test_skill_structure.py` enforces), ground their checklists in
+  **fetched** authoritative sources (OWASP/CIS/vendor docs) cited in the
+  skill body, and land with a golden-diff eval fixture under `evals/fixtures/`
+  (ideally also a `-clean` one).
 - Review skills report in the shared shape of `docs/finding-output.md` and
   inline its one-paragraph severity rubric word for word in `## Output`
-  (`tests/test_skill_structure.py` compares them); change the rubric in the doc
-  and every skill together. Respect its "Which skill owns what" table: a
-  defect is reported once, by its owning skill.
+  (`tests/test_skill_structure.py` compares them); change the rubric in the
+  doc, `skilldeck.lint.SEVERITY_RUBRIC` and every skill together. Respect its
+  "Which skill owns what" table: a defect is reported once, by its owning
+  skill.
 
 ## Shipping
 - PRs squash-merge to main: `gh pr merge <n> --squash --delete-branch` after CI

CONTRIBUTING.md

@@ -50,9 +50,17 @@ create them.
 Skills live in `src/skilldeck/skills/<name>/` as a `meta.yaml` + `skill.md`, authored
 once in an agent-neutral format — never hand-edit per-agent output. A skill's
 `meta.yaml` `name` must match its directory name, and its `capabilities` must declare
-what `skill.md` asks the agent to do (commands, network, credentials, edits). See
-[docs/authoring-skills.md](docs/authoring-skills.md) for the full guide, and bump that
-skill's own `version` in `meta.yaml` whenever its content changes.
+what `skill.md` asks the agent to do (commands, network, credentials, edits). Scaffold
+a new one and check your work with:
+
+```bash
+uv run --extra dev skilldeck new my-review --category security
+uv run --extra dev skilldeck validate my-review   # file, rule and fix per problem
+```
+
+See [docs/authoring-skills.md](docs/authoring-skills.md) for the full guide and the
+review path, and bump that skill's own `version` in `meta.yaml` whenever its content
+changes.
 
 Deprecating or removing a skill, dropping an agent, or making a major version change
 needs a `CHANGELOG.md` entry that names it, and CI checks for one. See

README.md

@@ -156,6 +156,10 @@ skilldeck provenance --verify
 # Machine-readable, schema-versioned skill catalog for tools (filters optional)
 skilldeck catalog --json
 skilldeck catalog --json --category security --agent claude
+
+# Author a skill: scaffold it, then check it against every rule, offline
+skilldeck new my-review --category security --dir skills
+skilldeck validate --skills-dir skills my-review
 ```
 
 `skilldeck catalog --json` is a stable contract for tools; see
@@ -222,9 +226,13 @@ release; the package remains unpublished today.
 ## Authoring skills
 
 Each skill is a directory under `src/skilldeck/skills/` containing a `meta.yaml`
-(including its capability declaration) and a `skill.md`, and nothing else. See
-[docs/authoring-skills.md](docs/authoring-skills.md), and
-follow the [contributor guide](CONTRIBUTING.md) for setup and validation.
+(including its capability declaration) and a `skill.md`, and nothing else.
+Start one with `skilldeck new` and check it with `skilldeck validate`, which
+names the file, rule and fix for every problem; in your own repository, pass
+`--dir` / `--skills-dir` to keep organization skills there. See
+[docs/authoring-skills.md](docs/authoring-skills.md), including the review path
+for official and organization skills, and follow the
+[contributor guide](CONTRIBUTING.md) for setup.
 
 ## Changelog and support