diff --git a/README.md b/README.md index b10bad5..150d7d4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,40 @@ A growing collection of reusable AI agent skills, policies, and workflows for everyday development. Start with clear commit messages and explicit security boundaries, then adapt the tools to your project. +[Quick start](#quick-start) ยท [Start contributing](#start-contributing) ยท [Contribution guide](CONTRIBUTING.md) + +## Quick start + +Use an AI coding assistant that can read repository files and run Git commands. These skills are Markdown instructions; no package installation is needed. Node.js is only needed for the demo tests. + +1. Copy [`.codex/skills/good-commit/SKILL.md`](.codex/skills/good-commit/SKILL.md) into the same path in your own Git repository. +2. Make a small change, such as clarifying a setup sentence in your README. +3. Ask your assistant: + + ```text + Read .codex/skills/good-commit/SKILL.md and propose a commit message for my current changes. + ``` + +4. Review the proposed message. For that README edit, an illustrative result is: + + ```text + docs(readme): ๐Ÿ“ clarify setup instructions + ``` + +The proposal does not stage, commit, or push changes. If anything is staged, the message describes the staged patch only. To use `/skill-commit`, merge the shortcut instructions from [AGENTS.md](AGENTS.md) into your project's existing instructions. + +Read the [partially staged changes walkthrough](docs/examples/partially-staged-walkthrough.md) for a worked example. + +## Start contributing + +Small documentation fixes and first-time contributions are welcome. Start with the [contribution guide](CONTRIBUTING.md), check the issue discussion and existing PRs, then choose a focused task: + +- [Document a breaking-change commit and migration (#8)](https://github.com/zmo2s/agent-toolbox/issues/8). +- [Show how to separate unrelated changes (#7)](https://github.com/zmo2s/agent-toolbox/issues/7). +- [Explain read-only database access with a fictional example (#3)](https://github.com/zmo2s/agent-toolbox/issues/3). + +[Browse open beginner issues](https://github.com/zmo2s/agent-toolbox/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22). Questions and documentation reviews are useful contributions too. + ## ๐ŸŽฌ Good Commit Demo See how the [Good Commit skill](.codex/skills/good-commit/SKILL.md) proposes a Conventional Commit message from your Git changes without automatically committing or pushing. diff --git a/docs/assets/social-preview.jpg b/docs/assets/social-preview.jpg new file mode 100644 index 0000000..16ef8f1 Binary files /dev/null and b/docs/assets/social-preview.jpg differ diff --git a/docs/examples/partially-staged-walkthrough.md b/docs/examples/partially-staged-walkthrough.md new file mode 100644 index 0000000..2a14926 --- /dev/null +++ b/docs/examples/partially-staged-walkthrough.md @@ -0,0 +1,68 @@ +# Write a commit message for what you staged, not everything you edited + +Suppose you add a todo validation test and also tidy another test in the same file. You stage only the new test. A commit message describing both edits would promise a change that is not in the commit. + +[Agent Toolbox](https://github.com/zmo2s/agent-toolbox) includes Good Commit, a reusable instruction file that asks an AI coding assistant to inspect the Git index before proposing a message. Here is a reproducible example using its small JavaScript demo. + +## Try it in a fresh clone + +You need Git, Node.js to run the demo tests, and an assistant that can read files and run Git commands. No npm dependencies are required. + +```bash +git clone https://github.com/zmo2s/agent-toolbox.git +cd agent-toolbox +git switch -c demo/partially-staged +``` + +Append this test to `test/todo.test.js`: + +```js +test("rejects an omitted title", () => { + assert.throws(() => addTodo(), /Todo title is required/); +}); +``` + +Stage that addition: + +```bash +git add test/todo.test.js +``` + +Now rename the first test from `creates a todo` to `creates an incomplete todo`, but leave that rename unstaged. Both edits are in the same file, yet only the new test belongs to the next commit. + +Inspect the two patches and run the tests: + +```bash +git status --short +git diff --cached +git diff +npm test +``` + +The file should appear as `MM test/todo.test.js`: the first `M` represents staged changes, and the second represents unstaged changes. The cached diff should contain only the appended test; the ordinary diff should contain only the rename. Test counts can change as the project grows. + +## Ask for a message + +Send your assistant this prompt from the clone: + +```text +Read .codex/skills/good-commit/SKILL.md and propose a commit message for my current changes. +``` + +An illustrative subject is: + +```text +test(core): โœ… cover omitted todo titles +``` + +The assistant should explain that this proposal covers the staged test addition and mention the unstaged test-name edit separately. It should not include that rename in the commit description, restage the entire file, or create a commit merely because you requested a message. Exact wording may vary; the important check is whether the message matches `git diff --cached`. + +## Reuse it in your project + +Copy [the Good Commit skill](../../.codex/skills/good-commit/SKILL.md) into `.codex/skills/good-commit/SKILL.md` in your repository and use the explicit prompt above. The `/skill-commit` shortcut additionally needs the routing instructions from [AGENTS.md](../../AGENTS.md). + +The skill provides instructions, not a guarantee of model behavior. Review the patch and proposed message before committing. You can try this workflow without installing the separate Security Guardian policy. + +## Help improve the examples + +First-time contributors are welcome. Try [documenting a breaking-change commit with migration guidance](https://github.com/zmo2s/agent-toolbox/issues/8), or [showing separate messages for unrelated changes](https://github.com/zmo2s/agent-toolbox/issues/7). Check the issue and open PRs before starting, and follow the [contribution guide](../../CONTRIBUTING.md).