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

feat(agents-canon): AGENTS.md canon everywhere — bootstrap v2.0.0 writes AGENTS.md + CLAUDE.md pointer; 15 skills retarget triggers/rule refs from CLAUDE.md to AGENTS.md (semver bumps); dist rebuilt

Browse Source
This commit is contained in:
vitya
2026-08-12 20:36:25 +03:00
parent 6a33542d81
commit e431e9e142
41 changed files with 134 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
skills/project-bootstrap/SKILL.md
View File

@@ -1,10 +1,11 @@
---
name: project-bootstrap
author: ours
version: 1.13.0
version: 2.0.0
description: >
Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
.wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
.wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with
skill triggers + CLAUDE.md legacy pointer.
Creates remote Gitea repo and syncs projects-meta cache for greenfield projects.
Use this skill when the user says "initialize project", "bootstrap", "setup project",
"upgrade project", "add wiki", "add tasks", "start project", "set everything up",
@@ -46,7 +47,7 @@ Show the user a summary in one block — what was found, what will be created:
Mode: greenfield-full (new project + remote create)
Found: (empty directory)
Create: git .wiki .tasks CLAUDE.md .gitignore README.md remote
Create: git .wiki .tasks AGENTS.md CLAUDE.md .gitignore README.md remote
```
Ask one question: "Looks right? Shall we proceed?" — and wait for confirmation.
@@ -320,22 +321,41 @@ If `setup-tasks` is not installed, **stop** and tell the user — same rule as S
---
## Step 5 — CLAUDE.md
## Step 5 — AGENTS.md (canon) + CLAUDE.md pointer
Two paths, picked by file presence:
**Canon is `AGENTS.md`** (cross-agent standard: pi prefers `AGENTS.md` over
`CLAUDE.md` when both exist — confirmed in pi's `resource-loader`; Claude Code
reads `AGENTS.md` as fallback). `CLAUDE.md` is a legacy pointer file for
tooling that looks for it by name. Both files are always written together;
the canon content lives only in `AGENTS.md`.
### Init (file does not exist)
Three paths, picked by file presence:
Create `CLAUDE.md` from `assets/CLAUDE.md.template`. Substitute the platform line
on non-Windows hosts (`we're on Linux` / `we're on macOS` instead of
`we're on Windows`).
### Init (neither file exists)
### Upgrade (file exists) — idempotent merge
Create `AGENTS.md` from `assets/AGENTS.md.template` (canon content). Substitute
the platform line on non-Windows hosts (`we're on Linux` / `we're on macOS`
instead of `we're on Windows`). Then write the `CLAUDE.md` pointer:
```markdown
# CLAUDE.md — legacy pointer
Canon is `AGENTS.md`. Read `AGENTS.md` — it contains all project instructions.
```
### Migrate (CLAUDE.md exists, AGENTS.md does not)
The project predates the AGENTS.md canon. Offer to migrate: `git mv CLAUDE.md
AGENTS.md`, fix the first-line header if it was `# CLAUDE.md`, then write the
`CLAUDE.md` pointer. Ask one question — "Migrate CLAUDE.md → AGENTS.md?" —
and wait for confirmation. On confirm, proceed to the Upgrade merge below.
### Upgrade (AGENTS.md exists) — idempotent merge
Treat the template as the canonical trigger set and reconcile the existing file
against it. Re-runs are no-ops once the file is in canon.
1. Read the existing `CLAUDE.md`.
1. Read the existing `AGENTS.md`.
2. For each non-empty, non-comment line in the template, decide whether it's
already present:
- **Trigger lines** (everything except the platform line) — present iff any
@@ -346,19 +366,20 @@ against it. Re-runs are no-ops once the file is in canon.
matches `we're on (windows|linux|macos)` case-insensitively. If the user
pinned a different platform on purpose, **leave it alone**. Only append
the host-appropriate platform line when none of the three is present.
3. Collect missing lines. If none → print `CLAUDE.md already canon — no changes`
3. Collect missing lines. If none → print `AGENTS.md already canon — no changes`
and skip to Step 5.5.
4. Show the user the diff (N lines, exact text to append) and ask one question:
"Append these N missing canonical triggers to the end of CLAUDE.md?" Wait
"Append these N missing canonical triggers to the end of AGENTS.md?" Wait
for explicit confirmation before writing.
5. On confirm: append a single newline (if the file doesn't end with one) and
then the missing lines, one per line. Don't rewrite the file — only append.
Don't reorder existing lines. Don't dedupe within the existing file.
6. Ensure the `CLAUDE.md` pointer exists; if missing, write it.
Template contents (`assets/CLAUDE.md.template` — source of truth):
Template contents (`assets/AGENTS.md.template` — source of truth):
```markdown
# CLAUDE.md
# AGENTS.md
# Agent instructions. Each line is a trigger for an installed skill.
talk like a caveman
@@ -388,8 +409,8 @@ if `pulling-before-work` is not in `~/.claude/skills/`; otherwise the trigger is
silently dead like any other absent skill.
The `follow project discipline` line activates the `project-discipline` skill,
which codifies four cross-project rules: (1) project CLAUDE.md / .wiki/CLAUDE.md
/ .tasks/ override defaults from any other skill; (2) all work on master/main,
which codifies four cross-project rules: (1) project AGENTS.md / CLAUDE.md /
.wiki/CLAUDE.md / .tasks/ override defaults from any other skill; (2) all work on master/main,
no feature branches without explicit user approval; (3) version bump on every
edit of versioned artifacts per semver, recorded in commit; (4) commit freely,
push only after explicit per-session approval. Install the skill on the host
@@ -468,7 +489,7 @@ If a delegated setup-skill is unavailable on this machine (e.g. user installed o
## Step 5.6 — Skill dependencies check (chat-only, never auto-install)
The `CLAUDE.md` template just written contains canonical trigger lines.
The `AGENTS.md` template just written contains canonical trigger lines.
Each one is a no-op unless the corresponding skill or plugin is installed
on the host. On a fresh machine these are often absent, and the user
won't know the trigger is silently dead. Detect what's missing on this
@@ -477,11 +498,11 @@ project file, never auto-install.
### Trigger → fulfiller map
Source of truth for this map is the canonical `assets/CLAUDE.md.template`.
Source of truth for this map is the canonical `assets/AGENTS.md.template`.
When a new trigger is added there, also add a row here in the same commit.
Mismatch between template and map → silent gaps in the recommendation.
| Trigger line in `CLAUDE.md` | Fulfiller | Kind | Detection path | Install command |
| Trigger line in `AGENTS.md` | Fulfiller | Kind | Detection path | Install command |
|---|---|---|---|---|
| `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` |
| `use project wiki` | `using-wiki` | skill | `~/.claude/skills/using-wiki/SKILL.md` | `bash scripts/install.sh using-wiki` |
@@ -497,7 +518,7 @@ Mismatch between template and map → silent gaps in the recommendation.
### Algorithm
1. Read the project's `CLAUDE.md` (just-written or pre-existing). Extract
1. Read the project's `AGENTS.md` (just-written or pre-existing). Extract
every non-empty, non-comment line — these are the active triggers for
THIS project. The user may have removed canonical lines on purpose;
respect that — only check what's actually in the file.
@@ -515,7 +536,7 @@ Mismatch between template and map → silent gaps in the recommendation.
- **All present** — print one line:
```
✅ all skill dependencies satisfied — every CLAUDE.md trigger has its fulfiller on this host.
✅ all skill dependencies satisfied — every AGENTS.md trigger has its fulfiller on this host.
```
Skip to Step 6.
@@ -524,9 +545,9 @@ Mismatch between template and map → silent gaps in the recommendation.
write it into any project file:
```
ℹ️ Recommended: install the following to fulfill CLAUDE.md triggers
ℹ️ Recommended: install the following to fulfill AGENTS.md triggers
The triggers below are present in CLAUDE.md but their fulfillers are
The triggers below are present in AGENTS.md but their fulfillers are
missing on this machine — they're silently no-ops until installed:
trigger fulfiller (kind)
@@ -555,7 +576,7 @@ Mismatch between template and map → silent gaps in the recommendation.
skill, and silently mutating user-level skill / plugin state without
consent is overreach. The recommendation is informational. The user can
install some / all / none of the recommendations, or remove canonical
lines from `CLAUDE.md` to lean the project's trigger set down.
lines from `AGENTS.md` to lean the project's trigger set down.
## Step 6 — Commit
@@ -567,7 +588,7 @@ git commit -m "chore: bootstrap project structure"
If the repo already had commits — commit only the files just created:
```bash
git add .wiki/ .tasks/ CLAUDE.md .gitignore README.md
git add .wiki/ .tasks/ AGENTS.md CLAUDE.md .gitignore README.md
git commit -m "chore: upgrade project structure"
```
@@ -581,7 +602,8 @@ Print a final report:
✅ Done! Created:
.wiki/ — project wiki (Karpathy method)
.tasks/ — task tracking system
CLAUDE.md — skill triggers
AGENTS.md — skill triggers (canon)
CLAUDE.md — legacy pointer
.gitignore — standard template
README.md — starter file
remote — Gitea repo created and pushed