flatten: skills directly at repo root, no skills/ subdir

~/dev/skills/skills/boss/ was visually awkward (skills/skills
read twice) and structurally unnecessary — the skills ARE the
repo's main content, not a sub-collection inside it.

Layout changes:
- boss/SKILL.md moves to the repo root
- skills/README.md (migration notes) moves to docs/migration.md
  where documentation-about-the-system belongs
- install.sh discovers skills via the SKILL.md marker file
  instead of a hardcoded skills/<name>/ path, so future skill
  additions just drop in at the root

Cross-references in boss/SKILL.md (../README.md, ../brainstorm,
etc.) now resolve against the repo root instead of the old
skills/ subdir, which is what they describe: top-level
README is the skill table; sibling skill dirs are the other
migrated skills.
This commit is contained in:
2026-05-28 15:46:25 +02:00
parent 9e10e9dfee
commit d7256e6f8c
4 changed files with 44 additions and 34 deletions
+105
View File
@@ -0,0 +1,105 @@
# Migration
This document tracks the migration from AILang's in-tree
`~/dev/ailang/skills/` into this plugin.
Each skill is one top-level directory at the repo root,
containing a `SKILL.md` plus the agent files it dispatches
under `agents/`. Agents live with their dispatching skill —
this is what makes the "no orphan agents" rule structurally
true rather than only documented.
The `boss` skill is the migration pilot (landed); the remaining
seven skills follow once the pattern is approved.
## Expected layout after migration
```
~/dev/skills/
├── README.md
├── INSTALL.md
├── install.sh
├── uninstall.sh
├── docs/
├── templates/
├── boss/ (pilot: landed)
│ └── SKILL.md
├── brainstorm/
│ ├── SKILL.md
│ └── agents/
│ └── grounding-check.md
├── planner/
│ ├── SKILL.md
│ └── agents/
│ └── plan-recon.md
├── implement/
│ ├── SKILL.md
│ └── agents/
│ ├── implement-orchestrator.md
│ ├── implementer.md
│ ├── spec-reviewer.md
│ ├── quality-reviewer.md
│ └── tester.md
├── audit/
│ ├── SKILL.md
│ └── agents/
│ ├── architect.md
│ └── bencher.md
├── debug/
│ ├── SKILL.md
│ └── agents/
│ └── debugger.md
├── fieldtest/
│ ├── SKILL.md
│ └── agents/
│ └── fieldtester.md
└── docwriter/
├── SKILL.md
└── agents/
└── docwriter.md
```
`boss` has no agents — it is itself the dispatcher of the
others, not a dispatcher-of-subagents.
`install.sh` walks the repo root, treats every top-level
directory that contains a `SKILL.md` as a skill, and symlinks
it into `~/.claude/skills/<name>`; if the skill has an
`agents/` subdirectory, that is symlinked into
`~/.claude/agents/<name>`. Claude Code's flat user-level
discovery still finds everything while the source tree keeps
the structural binding.
## Migration checklist per skill
1. Strip project-specific paths (`docs/specs`, `docs/plans`,
`design/INDEX.md`, `crates/`, `bench/`).
2. Strip project-specific commands (`cargo build`,
`bench/check.py`).
3. Replace literals with profile-slot references in prose.
4. Strip project vocabulary (`AILang`, `Form A`, `.ail.json`,
`Boss`); use the profile's vocabulary slots.
5. Strip project-specific contracts (honesty-rule,
feature-acceptance). These belong in the project's own
`CLAUDE.md`, not the plugin.
6. Verify the body still reads coherently for a generic
project — would it make sense in a Python web service?
A TypeScript library?
## Migration checklist per agent
1. Drop the `ailang-` prefix from the `name:` frontmatter
field. The skill path is the disambiguator.
2. Replace hardcoded standing-reading paths
(`design/INDEX.md`, etc.) with a reference to the profile's
`standing_reading` section.
3. Replace project-specific Iron Law clauses with the universal
discipline constants; project-specific clauses go to the
project's own `CLAUDE.md`.
4. Verify the body still reads coherently for a generic project
(see the per-skill checklist above).
5. Confirm the `tools:` frontmatter list matches the agent
template's role-based conventions (read-only review vs
implementation vs orchestrator).
6. Confirm the agent does **not** have `Agent` in its tools list
(no nested subagent dispatch).