docs(skills): name the project Skill path an Agent can actually reach

README.md

@@ -184,10 +184,20 @@ Run `skilld install --help` for every Agent target value.
 
 ## Author a Skill
 
-Run the skilld-maintained `generate-package-skill` Skill, or the Harness, to bootstrap a draft Skill for a package you maintain.
+Run a skilld-maintained Skill, or the Harness, to bootstrap a draft Skill you own.
+Use `generate-package-skill` for a package you maintain.
+Use `generate-project-skill` for the project you work in.
 Edit the draft, commit it to your Repository, and own it from there.
 skilld lists it with your name and a link to the file.
 
+```sh
+skilld run skilld-dev/skilld/generate-project-skill
+skilld run skilld-dev/skilld/generate-package-skill
+```
+
+A project Skill carries the search commands your Agent repeats against real files.
+It replaces the v2 local documentation index.
+
 The skilld-maintained Skills:
 
 - [`skilld`](./skills/skilld): search, run, and install Skills with the CLI

crates/skilld-command/src/lib.rs

@@ -785,7 +785,7 @@ fn v2_command(mut args: Vec<OsString>) -> V2Command {
             return V2Command::Removed(CommandError::usage(
                 "REMOVED_COMMAND",
                 format!(
-                    "skilld v3 has no author command. Ask your Agent to run the generate-package-skill or review-skill Skill, or use skilld-harness. See {MIGRATION_GUIDE}"
+                    "skilld v3 has no author command. Ask your Agent to run the generate-package-skill, generate-project-skill, or review-skill Skill, or use skilld-harness. See {MIGRATION_GUIDE}"
                 ),
             ));
         }

crates/skilld-command/tests/v2_commands.rs

@@ -77,6 +77,7 @@ fn removed_v2_commands_name_their_replacement() {
     assert!(stdout.is_empty());
     assert!(stderr.starts_with("REMOVED_COMMAND"), "{stderr}");
     assert!(stderr.contains("generate-package-skill"), "{stderr}");
+    assert!(stderr.contains("generate-project-skill"), "{stderr}");
 
     for command in [
         "watch",

docs/migrate-v2-to-v3.md

@@ -136,6 +136,7 @@ It cannot restore a v2 lockfile.
 | `skilld whoami` | Still works as `skilld auth status` |
 | `skilld logout` | Still works as `skilld auth logout` |
 | `skilld prepare` | Still works as `skilld install`, which restores the v3 lockfile |
+| `skilld search -p PACKAGE` | Not supported. v3 `skilld search` queries the registry. Run `generate-project-skill` so an Agent searches your files directly |
 | `skilld author package` | Run `generate-package-skill` with an Agent, or use Harness `PackageSkill` |
 | `skilld author validate` | Run `review-skill` with an Agent, or use Harness `ReviewSkill` |
 | `skilld author assemble` | Apply approved Agent changes, or let Harness promote checked output |

skills/generate-project-skill/SKILL.md

@@ -24,14 +24,28 @@ Ask for the destination only when the request does not provide one.
 
 ## Project navigation
 
-1. Identify the project name, purpose, key files, and main directories.
-2. Use project-relative paths for every file pointer.
-3. Add focused search commands for source and documentation.
-4. Keep search results linked to the real project files.
+The Skill must let an Agent find any part of the project without a prior index.
+
+1. Name the project from its manifest. Use the directory name when no manifest names it.
+2. List the entry points the manifest declares, such as `main`, `module`, `types`, `exports`, and `bin`.
+3. List the source and documentation directories an Agent reads most.
+4. Use project-relative paths for every file pointer.
 5. Never add a generated directory prefix to a project-relative path.
-6. Tell the Agent when project changes require a new Skill run.
+6. Give search commands the Agent can repeat, scoped to those directories.
+7. Prefer `rg` for search. Name the directories to skip in the command.
+8. Tell the Agent when project changes require a new Skill run.
+
+Write the search commands so their results point at real project files.
+
+Skip these paths while collecting project files:
+
+- version-control data, such as `.git`
+- dependency directories, such as `node_modules` and `vendor`
+- generated output, such as `dist`, `build`, `target`, `.output`, `.nuxt`, and `.next`
+- caches and reports, such as `coverage`
+- credential files, such as `.env` and any private key
 
-Ignore dependency directories, version-control data, generated output, caches, and credentials.
+Skip any file larger than 512 KB.
 Do not follow symbolic links while collecting project files.
 
 ## Output

skills/skilld/SKILL.md

@@ -75,6 +75,30 @@ A `verified` status covers where the Skill came from.
 It does not cover what the instructions ask you to do.
 If the status is `unverified`, tell the user before you follow the Skill.
 
+## Author a Skill from the user's own code
+
+The skilld CLI has no generation command.
+Authoring lives in skilld-maintained Skills that you run.
+
+Run the Skill that matches the request:
+
+```sh
+skilld run skilld-dev/skilld/generate-project-skill --json
+skilld run skilld-dev/skilld/generate-package-skill --json
+skilld run skilld-dev/skilld/review-skill --json
+```
+
+Use `generate-project-skill` for the current project or workspace.
+Use `generate-package-skill` for a package the user maintains.
+Use `review-skill` before the user publishes a Skill.
+
+Read the printed SKILL.md, then follow it for this project.
+Write the draft where the user asks, and show the files for review.
+Do not replace an existing Skill until the user approves the draft.
+Do not install or publish a draft the user has not read.
+
+The user owns the draft. They commit it to their own Repository.
+
 ## List the Skills a Repository, curator, or collection names
 
 skilld.dev prints refs that name several Skills: