AILang/skills

AILang Skill System

This directory holds the project-local development skills. A skill is a SKILL.md plus the agents that skill primarily dispatches. Skills formalise the AILang development cycle into named, trigger-bound discipline so the orchestrator (me) cannot accidentally diverge from established practice without explicitly violating a named rule.

The system was bootstrapped on 2026-05-09. See docs/specs/2026-05-09-skill-system.md for the design and docs/JOURNAL.md ("Skill system live") for the rationale.

The five skills

Skill	Trigger	Output	Mandatory?
brainstorm	New milestone starting	docs/specs/<milestone>.md	Hard-gate before plan
plan	New iteration within an open milestone	docs/plans/<iteration>.md	Hard-gate before implement
implement	Plan exists	Code + tests + per-task commits + JOURNAL entry	Standard iteration path
audit	Milestone closing OR baseline drift suspected	Drift report + bench-regression report + rustdoc audit	Mandatory at milestone close
debug	Bug encountered (failing test, segfault, wrong stdout)	RED-test commit + cause analysis	Mandatory RED-first for any bug

Pipeline

[new milestone]                        [bug observed]
       |                                      |
       v                                      v
 brainstorm  ->  plan  ->  implement      debug -> implement (mini)
       (per iteration loop)
                  |
       [milestone close]
                  |
                  v
                audit  --(clean)-->  next milestone
                       --(drift)-->  plan + implement (tidy iteration)
                                     OR ratify in DESIGN.md

Skipping rules are codified in each SKILL.md. Ad-hoc skipping is forbidden by design.

Agent roster

Agents live next to the skill that primarily dispatches them. There are no orphan agents (an anti-pattern after the 2026-05-09 build-out).

Agent	Path	Dispatched by skill
ailang-implementer	implement/agents/	implement
ailang-tester	implement/agents/	implement (E2E coverage)
ailang-architect	audit/agents/	audit
ailang-bencher	audit/agents/	audit (regression diagnostics)
ailang-docwriter	audit/agents/	audit (rustdoc-drift branch)
ailang-debugger	debug/agents/	debug

Each agent file has YAML frontmatter (name, description, tools) plus a system-prompt body. The description field is the one-sentence summary the orchestrator (or a skill) reads to decide whether to dispatch.

Subagent-type discovery

Subagent dispatch needs the agent files reachable under .claude/agents/. The repo provides one symlink per skill (tracked in git, no setup needed after clone):

.claude/agents/implement -> skills/implement/agents
.claude/agents/audit     -> skills/audit/agents
.claude/agents/debug     -> skills/debug/agents

Conventions

• No orphan agents. Every agent lives under the skill that dispatches it. If a recurring need does not fit any skill, raise the question in docs/JOURNAL.md before adding the agent.
• Agents do not call other agents. The dirigierende skill composes (e.g. implement dispatches implementer, then a separate spec-compliance reviewer, then a code-quality reviewer).
• Mandatory reading order stays in the agent file. Skills provide task-specific context (plan extract, bug symptom, drift item) on top of the agent's standing reading list.
• Skill and agent definitions are reviewable code. Edits go through git. Commit messages name why the role shifted.

Adding a new skill

1. Decide what triggers it and what it produces.
2. Write skills/<name>/SKILL.md with frontmatter (name, description starting "Use when…"). Keep the description trigger-focused; never a workflow summary.
3. If the skill dispatches subagents, add them under skills/<name>/agents/ and create .claude/agents/<name> as a symlink to that directory.
4. Update this file (skill table + agent roster).
5. If the skill replaces or supersedes a CLAUDE.md section, migrate that section: leave a one-line pointer in CLAUDE.md.

Adding a new agent

1. Decide which skill primarily dispatches it.
2. Add the .md file under that skill's agents/ directory.
3. Update the agent roster above and the dispatching skill's "Cross-references" section.
4. If the agent is genuinely standalone (no skill dispatches it), raise the question in docs/JOURNAL.md first.