skills/AGENTS.md

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/.
• Skill source lives under skills/<name>/. Do not edit generated links under .agents/skills/ or .claude/skills/ as source.
• Run nix flake check before considering a repository-wide change complete. The check builds every packaged skill plus the Home Manager module, shell hook, and benchmark core tests.
• 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.

Gotchas

• python3 is supplied by the default Nix dev shell, not the ambient environment. Enter nix develop before running Python-based project tools.
• 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.
• 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.