feat(kyberforge): retarget skill-author to author into .apm/skills/

Skills now migrate from hand-authored plugin.json to Microsoft APM
(apm.yml + .apm/) per ADR-0015/issue #89. skill-author's write location
switches accordingly: walk up from the destination to the nearest
ancestor apm.yml declaring a type: field (skipping type:-less
marketplace-only manifests) and scaffold into <package-root>/.apm/skills/
<name>/. Standalone authoring (no apm.yml/.git anywhere, e.g.
~/.agents/skills/) is unchanged — only the old plugin.json-based path is
replaced, not standalone mode.

Refs: #89

plugins/kyberforge/skills/skill-author/SKILL.md

@@ -38,6 +38,11 @@ Determine which flow to follow before touching the filesystem:
 
 Signals include: grill session output, `/skill-audit` findings (PASS/FAIL punch list), inline user feedback, session context describing what went wrong.
 
+**Before running the scaffold script**, judge whether the destination is meant to be inside an APM package — the script can't tell "no package here" apart from "package not scaffolded yet":
+
+- Package intent but no `type:`-bearing `apm.yml` found at/above the destination (e.g. "add to my apm package", or a sibling `.apm/`/`apm.yml` exists nearby) → **stop**, tell the user to run `/apm-workflow configure` (`apm plugin init`, from inside the package directory) first, then retry. Don't fall through to standalone mode.
+- Otherwise (a `~/`-rooted destination, or no package context implied) → run `scripts/new-skill.sh`; it resolves package vs. standalone automatically (see Step 1).
+
 ## Creating a new skill
 
 ### Prerequisites
@@ -51,33 +56,42 @@ Design for one coherent user intent — skills too narrow force multiple loads p
 - [ ] A clear purpose — what specific task will this skill handle?
 - [ ] Trigger scenarios — when should an agent activate it, including indirect cases?
 - [ ] Skill name (kebab-case) and destination path
-- [ ] Capture `git log --oneline -1` now, before touching the filesystem — Step 6 needs it to verify a real commit landed
+- [ ] Capture `git log --oneline -1` now, before touching the filesystem — Step 7 needs it to verify a real commit landed
 
 If any are missing, stop and ask the user before proceeding.
 
-**Requires `/skill-audit`** — used in Step 6 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing.
+**Requires `/skill-audit`** — used in Step 7 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing.
 
 ### Step 1 — Scaffold
 
-Run the copy script with the skill name and destination directory:
+Run the copy script with the skill name and a path inside or at the target:
 
 ```bash
-bash scripts/new-skill.sh <skill-name> <destination-dir>
+bash scripts/new-skill.sh <skill-name> <path>
 ```
 
+The script walks up from `<path>` for a package boundary: an ancestor `apm.yml` with a top-level `type:` field (`instructions`/`skill`/`hybrid`/`prompts`) means **package mode** — scaffolds into `<package-root>/.apm/skills/<skill-name>/`, not under `<path>` (a subdirectory of the package works fine as `<path>`). A `type:`-less `apm.yml` is a marketplace-only manifest, skipped. Hitting `.git` or the filesystem root first means **standalone mode** — scaffolds directly into `<path>/<skill-name>/`, same as before.
+
 Examples:
 ```bash
+# Package mode — packages/my-pkg/apm.yml already has `type: skill`
+bash scripts/new-skill.sh my-tool packages/my-pkg/
+
+# Standalone mode — no apm.yml/.git above ~/.agents/skills/
 bash scripts/new-skill.sh my-tool ~/.agents/skills/
-bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/
 ```
 
-This creates `<destination-dir>/<skill-name>/` with annotated templates ready to fill in.
+The script prints which mode it used and where the skill landed — read its output.
 
-If the destination is inside a plugin directory (path contains a `plugin.json`), read `references/deployment-modes.md` before adding any file references to SKILL.md.
+In package mode, read `references/deployment-modes.md` before adding any file references to SKILL.md.
 
-### Step 2 — Fill in SKILL.md
+### Step 2 — Update `apm.yml` includes (package mode only)
 
-Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.
+Skip in standalone mode. In package mode, check the resolved package's `apm.yml`: if `includes:` is an explicit list (not `auto`), append `.apm/skills/<skill-name>/` to it if not already present, preserving YAML formatting. If `includes: auto` or the field is absent, do nothing — `auto` already covers the new skill. Use Read/Edit directly on `apm.yml`; this isn't part of `scripts/new-skill.sh`.
+
+### Step 3 — Fill in SKILL.md
+
+Open the new skill's `SKILL.md` (the path Step 1 printed). Replace every `FILL IN:` placeholder.
 
 **Frontmatter**
 
@@ -97,7 +111,7 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
 - `metadata` — key-value map; use `author`, `version`, `category`; add `source_keys` now (see below) if research sources are in context
 - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
 
-**`metadata.source_keys`** — if research sources are in context, list the relevant slugs here as you write the body; don't defer this to Step 5. Agents that fill in source_keys late tend to omit it entirely. Example:
+**`metadata.source_keys`** — if research sources are in context, list the relevant slugs here as you write the body; don't defer this to Step 6. Agents that fill in source_keys late tend to omit it entirely. Example:
 ```yaml
 metadata:
   source_keys:
@@ -105,7 +119,7 @@ metadata:
     - another-slug
 ```
 
-**Embedding org-specific policy** — if a skill encodes a rule sourced from an org convention file (e.g. `core/instructions/*.md`), inline that content directly into the skill (SKILL.md or a `references/` file) rather than pointing to the file's path. Plugins must be self-contained and portable — the org file may not exist wherever the plugin is installed, and in this repo such files are meant to be deleted once their content is fully embedded downstream. Tag the inlined content with a `source_keys` entry using the same `references/sources.md` schema as Step 5, noting in the `Research doc:` field that the source is an org convention rather than a plugin research corpus entry, so provenance survives after the source file is gone.
+**Embedding org-specific policy** — if a skill encodes a rule sourced from an org convention file (e.g. `core/instructions/*.md`), inline that content directly into the skill (SKILL.md or a `references/` file) rather than pointing to the file's path. Plugins must be self-contained and portable — the org file may not exist wherever the plugin is installed, and in this repo such files are meant to be deleted once their content is fully embedded downstream. Tag the inlined content with a `source_keys` entry using the same `references/sources.md` schema as Step 6, noting in the `Research doc:` field that the source is an org convention rather than a plugin research corpus entry, so provenance survives after the source file is gone.
 
 **Body — include only what the agent lacks**
 
@@ -175,7 +189,7 @@ Keep `SKILL.md` under 500 lines; 5,000 tokens is the recommended body budget. Wh
 - Move reference material to `references/<topic>.md` and load it conditionally
 - Bundle repeated executable logic into `scripts/` rather than reinventing each run
 
-### Step 3 — Add scripts (if needed)
+### Step 4 — Add scripts (if needed)
 
 Place executable scripts in `scripts/`. Critical rule: **no interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin.
 
@@ -183,7 +197,7 @@ If adding a script, read `references/scripts.md` first — it covers the full co
 
 If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory.
 
-### Step 4 — Add references, assets, and tests (if needed)
+### Step 5 — Add references, assets, and tests (if needed)
 
 **`references/`** — additional documentation loaded on demand. One topic per file.
 Reference conditionally from SKILL.md: `If <condition>, read references/<file>.md`.
@@ -198,7 +212,7 @@ not in `scripts/`. See `tests/README.md` for setup instructions.
 
 If not needed, delete the placeholder READMEs and their directories.
 
-### Step 5 — Populate or delete `references/sources.md`
+### Step 6 — Populate or delete `references/sources.md`
 
 If a research `sources.md` is present in the conversation context:
 
@@ -210,7 +224,7 @@ If a research `sources.md` is present in the conversation context:
 
 If no research `sources.md` is in context, delete `references/sources.md`.
 
-### Step 6 — Validate and close
+### Step 7 — Validate and close
 
 Before running the audit, confirm:
 - [ ] Skill name matches the directory name exactly
@@ -218,7 +232,7 @@ Before running the audit, confirm:
 - [ ] Body has at least one non-empty section
 - [ ] No `FILL IN:` placeholders remain in any file
 
-Run `/skill-audit` on `<destination-dir>/<skill-name>`.
+Run `/skill-audit` on the skill directory Step 1 reported — either `<package-root>/.apm/skills/<skill-name>/` or `<path>/<skill-name>/`.
 
 All FAIL findings must be resolved before the skill is considered done.