nest agents under their dispatching skill
Top-level agents/ was an arbitrary flat layout from the skeleton commit, with no substantive reason behind it. Mirroring AILang's convention (skills/<name>/agents/<agent>.md) is strictly better: it makes the "no orphan agents" rule structurally true — you cannot place an agent file outside a skill — and it keeps the skill/agent binding visible at first glance. Claude Code's user-level discovery is unaffected: install.sh now symlinks ~/.claude/agents/<name> to skills/<name>/agents/ for each skill that has an agents/ subdirectory. The .claude/ registry stays flat; the source tree stays nested. The two checklists previously living in agents/README.md are folded into skills/README.md.
This commit is contained in:
@@ -1,54 +0,0 @@
|
||||
# agents/
|
||||
|
||||
One subdirectory per skill, mirroring the `skills/` layout.
|
||||
Each holds the agent files that the corresponding skill
|
||||
dispatches.
|
||||
|
||||
The skeleton commit ships this directory empty. Agent files
|
||||
are migrated from AILang's in-tree
|
||||
`~/dev/ailang/skills/<skill>/agents/` and generalised against
|
||||
the agent template (`../docs/agent-template.md`) and the
|
||||
profile schema (`../docs/profile-schema.md`) in **iteration 1**.
|
||||
|
||||
Expected layout after migration:
|
||||
|
||||
```
|
||||
agents/
|
||||
├── brainstorm/
|
||||
│ └── grounding-check.md
|
||||
├── planner/
|
||||
│ └── plan-recon.md
|
||||
├── implement/
|
||||
│ ├── implement-orchestrator.md
|
||||
│ ├── implementer.md
|
||||
│ ├── spec-reviewer.md
|
||||
│ ├── quality-reviewer.md
|
||||
│ └── tester.md
|
||||
├── audit/
|
||||
│ ├── architect.md
|
||||
│ └── bencher.md
|
||||
├── debug/
|
||||
│ └── debugger.md
|
||||
├── fieldtest/
|
||||
│ └── fieldtester.md
|
||||
└── docwriter/
|
||||
└── docwriter.md
|
||||
```
|
||||
|
||||
Migration checklist per agent:
|
||||
|
||||
1. Drop the `ailang-` prefix from the `name:` frontmatter
|
||||
field. The agent 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 skills/ migration checklist).
|
||||
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).
|
||||
+10
-13
@@ -1,11 +1,13 @@
|
||||
#!/usr/bin/env bash
|
||||
# Install the skills plugin globally into ~/.claude/.
|
||||
#
|
||||
# Creates symlinks from ~/.claude/skills/<name> and
|
||||
# ~/.claude/agents/<name> into this repo's skills/ and agents/
|
||||
# subdirectories. Idempotent — existing symlinks pointing to
|
||||
# this repo are left alone; existing entries that point elsewhere
|
||||
# are reported and skipped.
|
||||
# For each skill <name> under skills/<name>/, creates symlinks:
|
||||
# ~/.claude/skills/<name> -> <repo>/skills/<name>
|
||||
# ~/.claude/agents/<name> -> <repo>/skills/<name>/agents (if that dir exists)
|
||||
#
|
||||
# Idempotent — existing symlinks pointing to this repo are left
|
||||
# alone; existing entries that point elsewhere are reported and
|
||||
# skipped.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
@@ -42,14 +44,9 @@ if [ -d "$REPO_DIR/skills" ]; then
|
||||
[ -d "$s" ] || continue
|
||||
name="$(basename "$s")"
|
||||
link_one "$s" "$CLAUDE_SKILLS/$name"
|
||||
done
|
||||
fi
|
||||
|
||||
if [ -d "$REPO_DIR/agents" ]; then
|
||||
for a in "$REPO_DIR"/agents/*/; do
|
||||
[ -d "$a" ] || continue
|
||||
name="$(basename "$a")"
|
||||
link_one "$a" "$CLAUDE_AGENTS/$name"
|
||||
if [ -d "$s/agents" ]; then
|
||||
link_one "$s/agents" "$CLAUDE_AGENTS/$name"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
|
||||
+58
-11
@@ -1,34 +1,63 @@
|
||||
# skills/
|
||||
|
||||
One subdirectory per skill, each containing a `SKILL.md` plus
|
||||
any skill-local resources.
|
||||
the agent files that skill dispatches under `agents/`. Agents
|
||||
live with their dispatching skill, not in a parallel top-level
|
||||
directory — this is what makes the "no orphan agents" rule
|
||||
structurally true rather than only documented.
|
||||
|
||||
The skeleton commit ships this directory empty. The actual
|
||||
skill bodies are migrated from AILang's in-tree
|
||||
skill bodies and agents are migrated from AILang's in-tree
|
||||
`~/dev/ailang/skills/` and generalised against the profile
|
||||
schema (`../docs/profile-schema.md`) in **iteration 1**.
|
||||
schema (`../docs/profile-schema.md`) and the agent template
|
||||
(`../docs/agent-template.md`) in **iteration 1**.
|
||||
|
||||
Expected layout after migration:
|
||||
|
||||
```
|
||||
skills/
|
||||
├── brainstorm/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ └── grounding-check.md
|
||||
├── planner/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ └── plan-recon.md
|
||||
├── implement/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ ├── implement-orchestrator.md
|
||||
│ ├── implementer.md
|
||||
│ ├── spec-reviewer.md
|
||||
│ ├── quality-reviewer.md
|
||||
│ └── tester.md
|
||||
├── audit/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ ├── architect.md
|
||||
│ └── bencher.md
|
||||
├── debug/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ └── debugger.md
|
||||
├── fieldtest/
|
||||
│ └── SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ └── fieldtester.md
|
||||
└── docwriter/
|
||||
└── SKILL.md
|
||||
├── SKILL.md
|
||||
└── agents/
|
||||
└── docwriter.md
|
||||
```
|
||||
|
||||
Migration checklist per skill:
|
||||
`install.sh` symlinks each skill's directory into
|
||||
`~/.claude/skills/<name>` and each skill's `agents/`
|
||||
subdirectory into `~/.claude/agents/<name>`, so 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/`).
|
||||
@@ -43,3 +72,21 @@ Migration checklist per skill:
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user