starred/nix-config
1
0 Fork 0
mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:46 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

refactor(agents): pin global skills and trim always-loaded context (#427)

Browse Source 
* feat(agents): pin global skills as flake inputs
* refactor(agents): trim always-loaded agent context
This commit is contained in:
ryan4yin | 二花 authored and GitHub committed 2026-10-10 12:16:56 +08:00
1 parent 0d7c4d7cc1
commit 9d69832ff7
14 files changed
+426 -194
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

agents/README.md
+70 -45
View File
@@ -1,14 +1,14 @@
# Agents
Portable agent resources shared across projects: the global baseline rules, custom global skills,
Portable agent resources shared across projects: the global baseline rules, the global skills,
behavioral scenarios, and reference snippets for external tooling.
Home Manager links the rules and each custom skill into the agents' config locations. The resource
files here remain portable Markdown; deployment lives in the Home Manager module.
Home Manager links the rules and skills into the agents' config locations. The resource files here
remain portable Markdown; deployment lives in the Home Manager module.
It is shared across projects. Repo-scoped task procedures for one repository belong elsewhere: put
them in that repository's `.agents/skills/` (note the leading dot), which OpenCode and compatible
tools discover automatically. In a repository, use the layers this way:
Repo-scoped task procedures for one repository belong elsewhere: put them in that repository's
`.agents/skills/` (note the leading dot), which agents discover automatically. In a repository, use
the layers this way:
- `AGENTS.md`: always-loaded map and hard safety rules; keep it short.
- `agents/skills/*/SKILL.md`: custom global procedures reused across repositories.
@@ -20,30 +20,34 @@ Keep one canonical home for each fact; link between layers instead of copying pa
## What this directory contains
- `AGENTS.md`: global baseline rules for coding agents.
- `skills/`: custom global skills, e.g. [`git-delivery`](skills/git-delivery/SKILL.md) for commit
messages, PR descriptions, review replies, and cleanup after merge.
- `global-rules.md`: global baseline rules for coding agents. It is deliberately not named
`AGENTS.md`: agents working in this checkout would load it a second time as nested instructions
for `agents/`.
- `skills/`: global skills kept in this repository, e.g.
[`git-delivery`](skills/git-delivery/SKILL.md) for commit messages, PR descriptions, review
replies, and cleanup after merge; its [README](skills/README.md) records every global skill and
its source.
- `evals/global-rules.md`: how to size and run evaluations for changes to the rules or skills, and
the behavioral scenarios.
- `install-tooling.md`: curated install snippets for external agent tooling (`npx skills`,
`npx ctx7`, tuios integration).
- `install-tooling.md`: install snippets for project-scoped skills and other external agent tooling.
The Nix side of the agents — deploying these rules, the agent CLIs, and their environment — lives in
the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README.md).
The Nix side of the agents — deploying the rules and skills, the agent CLIs, and their environment —
lives in the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README.md).
## Core workflow
1. Maintain shared boundaries in `agents/AGENTS.md` and task procedures in `agents/skills/`.
1. Maintain shared boundaries in `agents/global-rules.md` and task procedures in skills.
2. Configure permissions directly in the agent runtime; auto-approval is generally used.
3. Content changes reach the next agent session through out-of-store links; a running harness may
need a reload. Adding or removing deployed links requires a Home Manager switch, run by the user.
4. Use `install-tooling.md` as a reference when installing external agent tooling.
3. Content changes to the rules and to skills in `agents/skills/` reach the next agent session
through out-of-store links; a running harness may need a reload. Adding or removing a skill, or
moving a skill flake input, requires a Home Manager switch, run by the user.
4. Use `install-tooling.md` as a reference when installing project-scoped tooling.
## Maintaining global rules
Before adding or expanding a rule, read the current rules and identify the decision boundary that
needs to change. Keep reusable boundaries in `AGENTS.md`; put concrete incidents, bypass attempts,
and counterexamples in [behavioral scenarios](evals/global-rules.md).
needs to change. Keep reusable boundaries in `global-rules.md`; put concrete incidents, bypass
attempts, and counterexamples in [behavioral scenarios](evals/global-rules.md).
- If an existing rule already covers the incident, add or refine a scenario instead of another rule.
- If the boundary is missing or ambiguous, amend the relevant rule rather than append a special
@@ -59,44 +63,65 @@ the PR.
## Deployment
[`home/base/tui/agents/rules.nix`](../home/base/tui/agents/rules.nix) links `AGENTS.md` into every
supported agent config directory as an out-of-store symlink, so edits apply without a rebuild. The
per-agent target list lives in that module's
[`rules.nix`](../home/base/tui/agents/rules.nix) links `global-rules.md` into every supported agent
config directory as `AGENTS.md`, out-of-store, so edits apply without a rebuild. The per-agent
target list lives in that module's
[README](../home/base/tui/agents/README.md#deployed-rule-targets).
[`skills.nix`](../home/base/tui/agents/skills.nix) links every directory under `agents/skills/` and
the skills selected from pinned flake inputs into `~/.agents/skills/<name>`; see the module's
[global skills](../home/base/tui/agents/README.md#global-skills) section. To add a local skill,
create `agents/skills/<name>/SKILL.md`; the user activates it with a Home Manager switch. Links
point at the canonical checkout, so changes in another worktree deploy only after they are merged
there.
The module is imported through `home/base/tui`, so it covers the hosts that import
`home/linux/gui.nix` or the macOS `home/darwin` stack; core-only servers are unchanged.
[`home/base/tui/agents/skills.nix`](../home/base/tui/agents/skills.nix) links each custom skill
directory into `~/.agents/skills/<name>`, leaving third-party skills unmanaged; see the module's
[global skills](../home/base/tui/agents/README.md#global-skills) section. To add a skill, create
`agents/skills/<name>/SKILL.md` and add its link there; the user activates it with a Home Manager
switch. Links point at the canonical checkout, so changes in another worktree deploy only after they
are merged there.
The repository-root `AGENTS.md` contains guidance for this Nix configuration repository. It is not
the global rules source and is not deployed.
Permission configuration is not managed by Nix. The repository-root `AGENTS.md` contains guidance
for this Nix configuration repository only; it is not deployed.
Auto-approval controls tool prompting. The global rules still define task authorization, safety, and
secret handling.
## About `install-tooling.md`
Use it as a snippet library:
- review the commands
- select what you need
- run selected commands manually
## TODO
Ideas worth adopting once a concrete need appears; nothing here is implemented yet.
Remaining work on the agent context, ordered by expected payoff. The goal is fewer tokens per
session and closer adherence to these rules. Done so far: the rules source rename, the move of
global skills to flake inputs (dropping superpowers, `find-skills`, and `caveman`), the i-have-adhd
always-on block, and the table-padding and duplication cleanup in the repo skills.
- **Unified third-party skill and MCP management.** Third-party skills are installed with
`npx skills` and MCP servers are configured by hand per harness; custom global skills already have
Home Manager links. A single source for the remaining tools would be nicer, though MCP config
formats differ per client. Reference: `mirkolenz/infra` `options/home-manager/agents.nix` (custom
`programs.agents`, follows the Agent Skills spec).
- **Compress the global rules** and run the Smoke scenarios afterwards. Tool execution (~600 tokens)
repeats its code-mode, Bun, and heredoc guidance; move counterexample nuance such as evidence
reuse in impactful changes into [behavioral scenarios](evals/global-rules.md).
- **Fold `mattpocock/skills` `pr` into `git-delivery`**: before/after evidence, one-way or two-way
door, and blast radius for PR bodies.
- **Write a `testing-strategy` skill**: E2E of real workflows first, unit tests for logic and edge
cases E2E cannot reach.
- **Merge `ponytail-review` with a comment and doc pruning pass** (reference:
`MidAutumnMoon/TaysiTsuki` `home/agents/skills/prune-comments-and-docs`). Worth borrowing from
`garrytan/gstack` `review/checklist.md`: a critical pass before an informational one, reading
consumers outside the diff for a new enum value or loosened validator, a do-not-flag list, and
"zero findings is valid". Keep review report-only.
- **Adapt `wayfinder` in the fork** so its map and tickets default to local Markdown and research
stays local, instead of GitHub issues and pushed `research/` branches.
- **Adapt `domain-modeling` in the fork** to record decisions in the repository's existing documents
(here `AGENTS.md`, `WORKAROUNDS.md`, `SECURITY.md`, READMEs) and create `GLOSSARY.md` or ADRs only
where none exist.
- **Trim `find-docs`**: its description (~930 characters) is the longest in the catalog and says
"always use", and its body runs `npx ctx7@latest` unpinned and suggests `npm install -g`.
- **Borrow small gstack ideas into the rules**: completion statuses (done, done with concerns,
blocked, needs context); never call a failure pre-existing without running the same check on the
base branch; a subagent with no one to ask takes the recommended option but never a destructive or
publishing one.
- **Use progressive disclosure for large repo skills.** `nix-config-umu-game` (~3.5k tokens) keeps
its troubleshooting inline; move it to a reference file. Lower priority: `nix-config-secrets` §7
and `nixpkgs-review` §3.
- **Budget the always-loaded context in CI**: cap skill description length and rules size, as gstack
does for its catalog.
- **MCP servers** are still configured by hand per harness; they could come from the same Nix
source, though config formats differ per client. Reference: `mirkolenz/infra`
`options/home-manager/agents.nix`.
## Conventions
agents/evals/global-rules.md
+2 -2
View File
@@ -1,7 +1,7 @@
# Global rules and skills evaluation
Use these scenarios after changing `agents/AGENTS.md` or a custom skill in `agents/skills/`, and
keep them in sync with the text they test — a stale scenario is worse than none. Formatting or
Use these scenarios after changing `agents/global-rules.md` or a custom skill in `agents/skills/`,
and keep them in sync with the text they test — a stale scenario is worse than none. Formatting or
keyword checks are supplemental; they do not replace behavioral scenarios. Before adding rules or
scenarios, follow the [global rule maintenance guidance](../README.md#maintaining-global-rules).
agents/AGENTS.md → agents/global-rules.md
+23 -4
View File
@@ -192,7 +192,26 @@ For an impactful change, follow these steps in order, scaled to its risk:
- Agents MUST respond in the user's language (default English); use English for code, commands,
identifiers, comments, commit messages, PR text, and repository documentation, and keep literal UI
strings and match patterns in their original language.
- Be concise, concrete, and action-oriented: lead with the next action or the answer, number
multi-step work, restate state and the requested scope across turns, suppress tangents, and make
progress visible. When a change takes effect only after a restart or activation someone else
performs, report what is applied and what is still pending.
- Restate the requested scope across turns. When a change takes effect only after a restart or
activation someone else performs, report what is applied and what is still pending.
<!-- Verbatim from the i-have-adhd always-on snippet (ayghri/i-have-adhd INSTALL.md, 723af7d9);
the full skill comes from the `i-have-adhd` flake input. -->
<!-- prettier-ignore-start -->
## Output style
The reader has ADHD. Shape every response so it can be acted on:
1. Lead with the answer or next action: command, path, or snippet first.
2. Number multi-step work; one bounded action per step.
3. End with one next action doable in under two minutes.
4. Finish the current issue before raising a new one.
5. Restate progress each turn ("step 3 of 5 done").
6. Give time estimates in concrete units, never "a bit".
7. After a change, show what now works.
8. Errors: state location, cause, and fix. No drama.
9. Cap lists to 5 items.
10. No preamble, no recaps, no closers.
Exceptions: explain fully when asked to explain. Confirm before destructive actions. After three failed fixes, stop and name the doubtful assumption. If the request is ambiguous, ask one short question.
<!-- prettier-ignore-end -->
agents/install-tooling.md
+7 -58
View File
@@ -1,64 +1,20 @@
# Agent Tooling Commands
Reference commands for installing external agent tooling: skills via `npx skills`, the `ctx7` docs
tool, and the tuios harness integration. Keep the global set small and install task-specific skills
in the relevant project.
Reference commands for project-scoped skills and other external agent tooling. Global skills are not
installed here: they are pinned flake inputs or live in `agents/skills/`, deployed by Home Manager;
see [skills/README.md](skills/README.md). Do not install global skills with `npx skills add -g`; its
copies collide with the Home Manager links in `~/.agents/skills`.
This repository's own skills live in `.agents/skills/`: they are tracked in git and discovered
automatically, so do not install, overwrite, or remove them with `npx skills`. The commands below
are for external and global skills.
## Inspect and update installed skills
```bash
# list all installed skills (project + global)
npx skills list
# list only global skills
npx skills ls -g
# check for updates
npx skills check
# update all installed skills
npx skills update
```
automatically, so do not install, overwrite, or remove them with `npx skills`.
## Discover skills from repositories
```bash
# list skills in a repository
# list skills in a repository without installing anything
npx skills add anthropics/skills --list
```
## Global baseline
```bash
# structured planning, testing, debugging, review, and verification workflows
npx skills add -g obra/superpowers --skill '*'
# discover task-specific skills when needed
npx skills add -g vercel-labs/skills --skill 'find-skills'
```
`find-docs` is also installed globally from a local source, so it has no upstream install command.
## Optional global skills
```bash
# rewrite prose to sound natural while preserving claims and technical meaning
npx skills add -g blader/humanizer --skill 'humanizer'
# review code for unnecessary abstractions and over-engineering
npx skills add -g DietrichGebert/ponytail --skill 'ponytail-review'
# enable a terse response mode when context or token usage matters
npx skills add -g JuliusBrussee/caveman --skill 'caveman'
# shape replies for an ADHD reader: next action first, numbered steps, restated state
npx skills add -g ayghri/i-have-adhd --skill 'i-have-adhd'
```
## Optional project skills
Run these commands from the project root. They intentionally omit `-g`, so the skills apply only to
@@ -76,15 +32,13 @@ npx skills add anthropics/skills --skill 'webapp-testing'
npx skills add anthropics/skills --skill 'pdf'
# run CodeQL and Semgrep on repositories written in supported languages; not for pure Nix projects
# (CC-BY-SA-4.0: copies and modifications carry attribution and the same license)
npx skills add trailofbits/skills --skill 'codeql' --skill 'semgrep'
```
## Other agent tooling
```bash
# context7: up-to-date library docs and code examples for LLMs and agents
npx ctx7 setup
# tuios: register it as an MCP server for the harness (read-only, or --mcp-write
# for typing tools); also reports agent state into the tuios pane
tuios integration install opencode --mcp-write
@@ -92,12 +46,7 @@ tuios integration install opencode --mcp-write
References:
- https://github.com/obra/superpowers
- https://github.com/vercel-labs/skills
- https://github.com/blader/humanizer
- https://github.com/DietrichGebert/ponytail
- https://github.com/JuliusBrussee/caveman
- https://github.com/ayghri/i-have-adhd
- https://github.com/Gaurav-Gosain/tuios
- https://github.com/anthropics/skills
- https://github.com/trailofbits/skills
agents/skills/README.md
+55
View File
@@ -0,0 +1,55 @@
# Global skills
Agent Skills shared by every agent on this machine, deployed into `~/.agents/skills/<name>` by
[`skills.nix`](../../home/base/tui/agents/skills.nix). They come from two places:
- **Flake inputs** (pinned in `flake.lock`): linked from the Nix store, so an update is a lock bump
plus a Home Manager switch.
- **This directory** (`agents/skills/<name>/`): skills iterated on locally, linked out-of-store so
an edit applies on the next agent session; adding or removing one needs a switch.
Repository-scoped skills do not belong here; they live in the owning repository's `.agents/skills/`.
## Skills from flake inputs
| Skill | Input | Source |
| -------------------------- | ------------------- | ----------------------------------------------------------------------------------------- |
| `diagnosing-bugs` | `mattpocock-skills` | [ryan4yin/mattpocock-skills](https://github.com/ryan4yin/mattpocock-skills) `main` (fork) |
| `domain-modeling` | `mattpocock-skills` | same |
| `grill-with-docs` | `mattpocock-skills` | same |
| `grilling` | `mattpocock-skills` | same |
| `prototype` | `mattpocock-skills` | same |
| `research` | `mattpocock-skills` | same |
| `retro` | `mattpocock-skills` | same |
| `setup-matt-pocock-skills` | `mattpocock-skills` | same |
| `wayfinder` | `mattpocock-skills` | same |
| `writing-for-agents` | `mattpocock-skills` | same |
| `i-have-adhd` | `i-have-adhd` | [ryan4yin/i-have-adhd](https://github.com/ryan4yin/i-have-adhd) `main` (fork) |
| `humanizer` | `humanizer` | [blader/humanizer](https://github.com/blader/humanizer) `v3.1.0` |
| `find-docs` | `context7` | [upstash/context7](https://github.com/upstash/context7) commit `522c4db4` |
| `ponytail-review` | `ponytail` | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) `v5.1.0` |
Dependencies travel together: `grill-with-docs` and `wayfinder` call `grilling` and
`domain-modeling`; `wayfinder` also calls `research` and `prototype`, and points at
`setup-matt-pocock-skills` for the issue-tracker convention; `retro` calls `writing-for-agents`.
User-invoked skills (`disable-model-invocation: true`, plus `allow_implicit_invocation: false` in
`agents/openai.yaml` for Codex) stay out of the model's skill catalog: `grill-with-docs`,
`wayfinder`, `retro`, `setup-matt-pocock-skills`, and `i-have-adhd`. The global rules embed the
i-have-adhd always-on snippet, so the skill is only needed for its full ruleset.
The global rules take precedence over these skills. In particular, `wayfinder` defaults to GitHub
issues and pushes research branches; both are GitHub writes that need authorization, and a public
repository is the wrong place for an infrastructure decision map.
To update one: review the upstream diff as untrusted input, then `nix flake update <input>` (or move
the pinned tag/commit in `flake.nix`) and check `git diff flake.lock`.
## Skills in this directory
`git-delivery` is maintained here rather than pulled from an input: commit messages, PR text, review
replies, and cleanup after merge, all following the target repository's conventions. Edit it in
place; the change reaches the next agent session without a switch.
A third-party skill starts here only when it is being rewritten. Until then, pin it as a flake input
so the license and provenance stay with the upstream repository and the diff stays reviewable.