37 lines
2.6 KiB
Markdown
37 lines
2.6 KiB
Markdown
# 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.
|
|
- The installed `gitea-axi pr view` does not support `--fields`.
|
|
Use plain `gitea-axi pr view <number>`.
|