diff --git a/AGENTS.md b/AGENTS.md index 6cebb815f8aa59da384f3200a223b982bafcac5e..96f753953f3c2a7da7b7679f4d880411a9892244 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,10 +4,10 @@ Amolith's collection of Agent Skills—markdown-based documentation that extends ## Repository Structure -Each top-level directory is a skill. A skill's directory name **must match** its `name` frontmatter field. +Each directory under `skills/` is a skill. A skill's directory name **must match** its `name` frontmatter field. ``` -skill-name/ +skills/skill-name/ ├── SKILL.md # Required: YAML frontmatter + markdown instructions ├── references/ # Optional: additional documentation loaded on-demand ├── scripts/ # Optional: executable code @@ -16,10 +16,10 @@ skill-name/ ## Creating/Editing Skills -The `authoring-skills/` directory has the necessary info for, well, authoring skills. +The `skills/authoring-skills/` directory has the necessary info for, well, authoring skills. ## Design Principles 1. Progressive disclosure: Frontmatter loads at startup; SKILL.md body loads on activation; references/ load on-demand 2. Conciseness over completeness: Every token competes for context window space -3. Appropriate freedom: Match instruction specificity to task fragility (see `authoring-skills/references/patterns.md`) +3. Appropriate freedom: Match instruction specificity to task fragility (see `skills/authoring-skills/references/patterns.md`) diff --git a/README.md b/README.md index f0f0fbaede65831147fce64e6e678b205aad6e79..dd6b86337a07afca371efa3994f23be733076792 100644 --- a/README.md +++ b/README.md @@ -13,26 +13,23 @@ agent capabilities through a standardised format. ## Available Skills -- [authoring-skills](authoring-skills/SKILL.md): Creates well-structured - Agent Skills following best practices. Use when writing new skills, - reviewing existing skills, or when the user mentions skill authoring. - -- [formatting-commits](formatting-commits/SKILL.md): Creates commits - strictly following Conventional Commits format via the +- [authoring-skills](skills/authoring-skills/SKILL.md): Creates + well-structured Agent Skills following best practices. Use when + writing new skills, reviewing existing skills, or when the user + mentions skill authoring. +- [formatting-commits](skills/formatting-commits/SKILL.md): Creates + commits strictly following Conventional Commits format via the `formatted-commit` CLI. - -- [invoking-subagents](invoking-subagents/SKILL.md): Invokes ad-hoc - subagents to read through lots of data and extract relevant +- [invoking-subagents](skills/invoking-subagents/SKILL.md): Invokes + ad-hoc subagents to read through lots of data and extract relevant information. Useful for exploring repositories, reading git logs, reviewing large diffs. - -- [querying-documentation](querying-documentation/SKILL.md): Spawns - focused agents to search specific language/framework documentation and - answer moderately complex queries. - -- [resolving-secrets](resolving-secrets/SKILL.md): Wraps shell commands - to resolve secret references in environment variables. Use when - invoking `synu`, `crush`, `gh`, `hut`, etc. +- [querying-documentation](skills/querying-documentation/SKILL.md): + Spawns focused agents to search specific language/framework + documentation and answer moderately complex queries. +- [resolving-secrets](skills/resolving-secrets/SKILL.md): Wraps shell + commands to resolve secret references in environment variables. Use + when invoking `synu`, `crush`, `gh`, `hut`, etc. ## Installation @@ -50,19 +47,24 @@ Get it from your preferred/available package manager (definitely true on Linux, I assume so on macOS and Windows) ```sh +# Install all skills +stow -d skills -t ~/.config/crush/skills . + # Install specific skills -stow -t ~/.config/crush/skills authoring-skills formatting-commits +stow -d skills -t ~/.config/crush/skills authoring-skills … # Remove a skill -stow -D -t ~/.config/crush/skills formatting-commits +stow -D -d skills -t ~/.config/crush/skills formatting-commits ``` ### With symlinks ```sh +# Install all skills +for s in skills/*/; do ln -s "$PWD/$s" ~/.config/crush/skills/; done + # Install specific skills -ln -s "$PWD/authoring-skills" ~/.config/crush/skills/ -ln -s "$PWD/formatting-commits" ~/.config/crush/skills/ +ln -s "$PWD/skills/authoring-skills" ~/.config/crush/skills/ # Remove a skill rm ~/.config/crush/skills/formatting-commits diff --git a/authoring-skills/SKILL.md b/skills/authoring-skills/SKILL.md similarity index 100% rename from authoring-skills/SKILL.md rename to skills/authoring-skills/SKILL.md diff --git a/authoring-skills/references/checklist.md b/skills/authoring-skills/references/checklist.md similarity index 100% rename from authoring-skills/references/checklist.md rename to skills/authoring-skills/references/checklist.md diff --git a/authoring-skills/references/patterns.md b/skills/authoring-skills/references/patterns.md similarity index 100% rename from authoring-skills/references/patterns.md rename to skills/authoring-skills/references/patterns.md diff --git a/authoring-skills/references/specification.md b/skills/authoring-skills/references/specification.md similarity index 100% rename from authoring-skills/references/specification.md rename to skills/authoring-skills/references/specification.md diff --git a/formatting-commits/SKILL.md b/skills/formatting-commits/SKILL.md similarity index 100% rename from formatting-commits/SKILL.md rename to skills/formatting-commits/SKILL.md diff --git a/formatting-commits/references/installing-formatted-commit.md b/skills/formatting-commits/references/installing-formatted-commit.md similarity index 100% rename from formatting-commits/references/installing-formatted-commit.md rename to skills/formatting-commits/references/installing-formatted-commit.md diff --git a/invoking-subagents/SKILL.md b/skills/invoking-subagents/SKILL.md similarity index 100% rename from invoking-subagents/SKILL.md rename to skills/invoking-subagents/SKILL.md diff --git a/invoking-subagents/references/installing-synu.md b/skills/invoking-subagents/references/installing-synu.md similarity index 100% rename from invoking-subagents/references/installing-synu.md rename to skills/invoking-subagents/references/installing-synu.md diff --git a/querying-documentation/SKILL.md b/skills/querying-documentation/SKILL.md similarity index 100% rename from querying-documentation/SKILL.md rename to skills/querying-documentation/SKILL.md diff --git a/querying-documentation/references/installing-doc-agent.md b/skills/querying-documentation/references/installing-doc-agent.md similarity index 100% rename from querying-documentation/references/installing-doc-agent.md rename to skills/querying-documentation/references/installing-doc-agent.md diff --git a/resolving-secrets/SKILL.md b/skills/resolving-secrets/SKILL.md similarity index 100% rename from resolving-secrets/SKILL.md rename to skills/resolving-secrets/SKILL.md diff --git a/resolving-secrets/references/installing-opx.md b/skills/resolving-secrets/references/installing-opx.md similarity index 100% rename from resolving-secrets/references/installing-opx.md rename to skills/resolving-secrets/references/installing-opx.md