diff --git a/README.md b/README.md index 984a0a01..8e42ef30 100644 --- a/README.md +++ b/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 diff --git a/crates/skilld-command/src/lib.rs b/crates/skilld-command/src/lib.rs index b2620acf..237780cd 100644 --- a/crates/skilld-command/src/lib.rs +++ b/crates/skilld-command/src/lib.rs @@ -785,7 +785,7 @@ fn v2_command(mut args: Vec) -> 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}" ), )); } diff --git a/crates/skilld-command/tests/v2_commands.rs b/crates/skilld-command/tests/v2_commands.rs index b7e3e846..d1dbadf2 100644 --- a/crates/skilld-command/tests/v2_commands.rs +++ b/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", diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 43b46eab..ede890ab 100644 --- a/docs/migrate-v2-to-v3.md +++ b/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 | diff --git a/skills/generate-project-skill/SKILL.md b/skills/generate-project-skill/SKILL.md index 573d4505..5bf06f1e 100644 --- a/skills/generate-project-skill/SKILL.md +++ b/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 diff --git a/skills/skilld/SKILL.md b/skills/skilld/SKILL.md index 92af6f57..2016a4d7 100644 --- a/skills/skilld/SKILL.md +++ b/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: