alexion/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): support flat numbered artifacts

Browse Source
This commit is contained in:
alexion
2026-07-31 09:23:13 -04:00
parent 43280e4d4a
commit 8ad93c7617
5 changed files with 30 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
AGENTS.md
View File

@@ -1,7 +1,7 @@
# skills # skills
Personal agent skills packaged through Nix. Personal agent skills packaged through Nix.
The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/CONTEXT.md`. The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/011-skills-context.md`.
## Conventions ## Conventions
@@ -18,3 +18,13 @@ The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/sk
- `python3` is supplied by the default Nix dev shell, not the ambient environment. - `python3` is supplied by the default Nix dev shell, not the ambient environment.
Enter `nix develop` before running Python-based project tools. 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.

2
skills/consume/SKILL.md
View File

@@ -34,7 +34,7 @@ All reading of the wider AI-managed wiki goes through `/wiki` (step 3).
Resolve the artifact project directory as `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>`, where `<project>` is the lowercase basename of the target directory. Resolve the artifact project directory as `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>`, where `<project>` is the lowercase basename of the target directory.
Route the target through this ladder, first match wins: Route the target through this ladder, first match wins:
- An artifact project directory containing `spec/` or `tasks/` → a project: follow [`project.md`](project.md). - An artifact project directory containing flat `*-spec.md` or `*-task.md` artifacts → a project: follow [`project.md`](project.md).
- No rung matches → report that the target is not something consume knows how to read, write nothing, and stop. - No rung matches → report that the target is not something consume knows how to read, write nothing, and stop.
Done when a branch file is selected, or consume has stopped on an unsupported target. Done when a branch file is selected, or consume has stopped on an unsupported target.

9
skills/consume/project.md
View File

@@ -1,7 +1,7 @@
# project branch # project branch
How consume reads a project target, and what it clears afterward. How consume reads a project target, and what it clears afterward.
Reached from step 1 of [`SKILL.md`](SKILL.md) when the target's artifact project directory contains `spec/` or `tasks/`. Reached from step 1 of [`SKILL.md`](SKILL.md) when the target's flat artifact project directory contains `*-spec.md` or `*-task.md` artifacts.
## Read the source, mine the specs ## Read the source, mine the specs
@@ -10,7 +10,7 @@ Read it thoroughly enough to understand its current state and to surface the reu
A gotcha usually carries two separable things — a transferable principle and a concrete repo-specific answer — so surface both. A gotcha usually carries two separable things — a transferable principle and a concrete repo-specific answer — so surface both.
Step 4 of SKILL.md routes the principle to the pull channel and the residue to the target's push channel. Step 4 of SKILL.md routes the principle to the pull channel and the residue to the target's push channel.
The artifact project's `spec/` and `tasks/` directories are the canonical record of *why* — the reasoning, trade-offs, and intent behind what the code became. The artifact project's `*-spec.md` and `*-task.md` artifacts are the canonical record of *why* — the reasoning, trade-offs, and intent behind what the code became.
They are the richest source of the generalizable lessons, and cleanup destroys them, so mine their reasoning now or lose it. They are the richest source of the generalizable lessons, and cleanup destroys them, so mine their reasoning now or lose it.
But they are not current fact: where a spec or task disagrees with the source, the source wins, and where one describes work later abandoned or changed, the source is what actually happened. But they are not current fact: where a spec or task disagrees with the source, the source wins, and where one describes work later abandoned or changed, the source is what actually happened.
@@ -25,9 +25,8 @@ Do not create subdirectories there.
## Cleanup ## Cleanup
After the notes are written (step 6 of SKILL.md), delete the spec and task files that were present under the artifact project's `spec/` and `tasks/` directories when you read the project in step 2 — the scaffolding this run consumed. After the notes are written (step 6 of SKILL.md), delete the `*-spec.md` and `*-task.md` artifacts that were present in the flat artifact project directory when you read the project in step 2 — the scaffolding this run consumed.
A file added after that read is not swept up. A file added after that read is not swept up.
Remove `spec/` or `tasks/` when the cleanup leaves it empty.
Deleting those files can strand references to them. Deleting those files can strand references to them.
Scan the target and its artifact project directory for pointers to each file about to be deleted — in `AGENTS.md`, `CONTEXT.md`, ADRs, and sibling specs — and fix or remove each one, following the pointer wherever it lands rather than checking the push channel alone. Scan the target and its artifact project directory for pointers to each file about to be deleted — in `AGENTS.md`, context artifacts, ADRs, and sibling specs — and fix or remove each one, following the pointer wherever it lands rather than checking the push channel alone.

2
skills/grill/CONTEXT-FORMAT.md
View File

@@ -1,4 +1,4 @@
# CONTEXT.md Format # Context Artifact Format
## Structure ## Structure

24
skills/grill/SKILL.md
View File

@@ -22,20 +22,20 @@ This holds even when another skill invoked grill: grill delivers its summary and
## 1. Select the mode ## 1. Select the mode
Resolve the artifact root with `$(xdg-user-dir DOCUMENTS)/ai-artifacts`. Resolve the artifact root with `$(xdg-user-dir DOCUMENTS)/ai-artifacts`.
Use the lowercase basename of the current working directory as `<project>`. Use the lowercase basename of the current working directory as `<project>` and inspect `projects/<project>/` directly for its numbered `<project>-context.md` artifact.
The context file is `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>/CONTEXT.md`. Read the artifact root's `AGENTS.md` before any artifact write.
Its sibling `adr/` directory owns the project's ADRs. Create the project directory only when a write requires it.
Create the project directory and `adr/` only when a write requires them.
- **Domain Modeling Mode** — a context file was found. - **Domain Modeling Mode** — exactly one context artifact was found.
Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)). Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)).
- **Free Mode** — no context file, and the plan raises no project-specific vocabulary worth pinning down. - **Free Mode** — no context artifact was found, and the plan raises no project-specific vocabulary worth pinning down.
Run the interview with no document side effects. Run the interview with no document side effects.
- **Clarification** — no context file, but the plan introduces terms specific to this project that later work will need to use consistently — the kind of terms [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) admits, not general programming concepts. - **Clarification** — no context artifact was found, but the plan introduces terms specific to this project that later work will need to use consistently — the kind of terms [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) admits, not general programming concepts.
Before interviewing, ask whether to create a glossary. Before interviewing, ask whether to create a glossary.
If yes, create it at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>/CONTEXT.md` and continue in Domain Modeling Mode. If yes, allocate the next vault identifier through `.counter`, create `<NNN>-<project>-context.md`, and continue in Domain Modeling Mode.
If no, continue in Free Mode. If no, continue in Free Mode.
Stop and report the conflicting paths if more than one matching context artifact exists.
Done when the interview is running in Domain Modeling Mode or Free Mode. Done when the interview is running in Domain Modeling Mode or Free Mode.
## 2. Run the interview ## 2. Run the interview
@@ -66,9 +66,9 @@ Active only when step 1 selected this mode.
### Glossary ### Glossary
As a term crystallizes, update the context file right then — do not batch these to the end. As a term crystallizes, update the context artifact right then — do not batch these to the end.
When a settling term clashes with one already in the glossary, call it out and reconcile to a single canonical word. When a settling term clashes with one already in the glossary, call it out and reconcile to a single canonical word.
Keep the file a glossary and nothing else: vocabulary and ubiquitous language, no implementation detail. Keep the artifact a glossary and nothing else: vocabulary and ubiquitous language, no implementation detail.
Write it in the format of [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md). Write it in the format of [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md).
### ADRs ### ADRs
@@ -80,7 +80,9 @@ Offer to record an architectural decision only when all three hold:
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons. 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
If any of the three is missing, skip it. If any of the three is missing, skip it.
A recorded decision lives in the sibling `adr/` directory, numbered one past the highest already there (`0001-slug.md`), and can be a single paragraph: A recorded decision lives directly in the project's flat artifact directory.
Allocate its identifier through the vault-root `.counter` and name it `<NNN>-<scope-slug>-<decision-slug>-adr.md` according to the vault convention.
It can be a single paragraph:
> # {Short title of the decision} > # {Short title of the decision}
> >