From 25df5f8555d3187156d17661d7669c93bafd17f8 Mon Sep 17 00:00:00 2001 From: alexion Date: Wed, 26 Aug 2026 19:08:23 -0400 Subject: [PATCH] Update project agent instructions --- AGENTS.md | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3756dd4..bc3c9fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,29 @@ # skills Personal agent skills packaged through Nix. -The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/011-skills-context.md`. ## Conventions -- `AGENTS.md` is canonical for project instructions. - Context, ADRs, specs, and tasks live under `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/`. +- `AGENTS.md` is the canonical source for project instructions. - Skill source lives under `skills//`. - Do not edit generated links under `.agents/skills/` or `.claude/skills/` as source. + Do not edit generated links under `.agents/skills/` or `.claude/skills/`. - Deprecated skill source lives under `deprecated//`. -- Run `nix flake check` before considering a repository-wide change complete. +- Run `nix flake check` before marking a repository-wide change complete. The check builds every packaged skill plus the Home Manager module and shell hook. -- The dev shell may place Nix-delivered skills into `.agents/skills/` and maintain `.claude/skills` as a compatibility symlink. - Generated ignore entries belong in the root `.gitignore`, not inside `.agents/skills/`, because skill scanners honor ignore files inside scanned skill directories. +- The dev shell can place Nix-delivered skills into `.agents/skills/`. + It can maintain `.claude/skills` as a compatibility symlink. + Generated ignore entries belong in the root `.gitignore`, not inside `.agents/skills/`. + Skill scanners honor ignore files inside scanned skill directories. ## Gotchas -- A skill-local `GLOSSARY.md` is runtime reference for that skill and has no relationship to the project's AI-artifacts-vault context glossary. - This repository owns packaged skill sources only. Enabling, replacing, or removing them in a consumer repository such as dotfiles is outside its scope. - `nix flake check` evaluates the Git snapshot and omits untracked skill files. Use `nix flake check "path:$PWD"` to include a newly created skill before staging it. -- `$(xdg-user-dir DOCUMENTS)/ai-artifacts` is itself an Obsidian vault for AI-generated artifacts, distinct from the personal vault where AI-generated notes are forbidden. -- Project artifact filenames carry globally allocated identifiers. - Discover context and ADR artifacts through the AI artifacts vault convention rather than assuming fixed names or type directories. - Do not turn opportunistic use of another skill into a declared dependency. - Invocation of an unrelated skill remains the agent's discretion unless the current skill directly requires its contract. -- Do not instruct a skill to execute synchronously. - In-process execution is the baseline, while isolation and parallelism belong to an external caller or runtime. + The agent can invoke an unrelated skill at its discretion unless the current skill directly requires its contract. - When adapting an upstream skill, preserve mechanics the upstream skill leaves unspecified. - Customize only the surfaces required to fit the local workflow rather than turning incidental choices into new contracts. -- The installed `gitea-axi pr view` does not support `--fields`. - Use plain `gitea-axi pr view `. + Treat deliberate ambiguity as part of the skill's design. + Customize only the parts required to fit the local workflow. + Do not turn incidental choices into new contracts.