@awebai/oats 0.22.0

package/skills/skill-craft/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: skill-craft
+description: >-
+  How to create, evaluate, and maintain agent skills (SKILL.md files per the
+  Agent Skills standard). Use when writing a new skill, improving or debugging
+  an existing one (skill not triggering, agent ignoring instructions, skill too
+  long), turning a repeated procedure or correction into a skill, deciding
+  whether knowledge belongs in a skill versus the knowledge base versus
+  AGENTS.md, bundling scripts into skills, or evaluating whether a skill
+  actually helps. Based on the agentskills.io creator guides and Anthropic
+  best practices.
+---
+
+# Skill craft — create, evaluate, maintain
+
+A skill is a directory with a `SKILL.md` (YAML frontmatter + markdown body),
+optionally `scripts/`, `references/`, `assets/`. Agents load only `name` +
+`description` at startup; the body loads **only when the description matches
+the task** — the description carries the entire burden of triggering.
+
+## Where does this knowledge belong? (decide first)
+
+- **Repeatable procedure** ("how to do X, again and again") → **skill**.
+- **Declarative fact/decision/lesson** ("what is true and why") → **OKF
+  concept** in the knowledge base (see `okf` skill). Skills may reference
+  concepts for the why.
+- **Applies to every session of this agent** (role, boundaries, core workflow)
+  → **AGENTS.md** (see `soul-craft`). Rule of thumb: AGENTS.md is loaded
+  always — keep it minimal; skills load on demand — put domain workflows there.
+
+## Creating a skill
+
+**Ground it in real expertise — never generate from thin air.** The valuable
+content is what a capable model *doesn't* already know: your APIs, your
+conventions, the corrections you had to make. Best sources: a hands-on task
+you just completed (extract the steps that worked, the corrections given, the
+formats used), runbooks, review comments, real failures and their fixes. A
+skill with generic content ("handle errors appropriately") is worthless — cut
+or ground it.
+
+**Frontmatter rules** (spec + hard-won):
+- `name`: lowercase alphanum + hyphens, ≤64 chars, **must match the directory
+  name**, no leading/trailing/double hyphens.
+- `description`: ≤1024 chars, non-empty. ⚠️ **Use a `>-` block scalar if it
+  contains any `: ` colon-space** — an unquoted colon breaks YAML parsing and
+  the skill silently fails to load. Verify new skills actually load.
+
+**Write the description for triggering** (it's the only thing the agent sees
+before deciding):
+- Imperative: "Use when..." not "This skill does...".
+- Name the **user intents** it serves, not the implementation. Include
+  trigger phrases users actually say, and cover cases where they don't name
+  the domain ("even if they don't mention X").
+- Precise beats broad: an over-broad description fires on near-miss tasks
+  and pollutes context.
+
+**Write the body for a loaded context window** — it competes with everything
+else once loaded:
+- **Only what the agent would get wrong without it.** For every line ask:
+  "would removing this cause mistakes?" No → cut.
+- ≤500 lines / ~5k tokens. Larger → move detail to `references/` and tell the
+  agent **when** to load each file ("read references/errors.md if the API
+  returns non-200"), not just that it exists.
+- **Defaults, not menus**: pick one tool/approach, mention alternatives in
+  one line. Match prescriptiveness to fragility: fragile sequences get exact
+  commands ("run exactly this"); judgment tasks get goals + why.
+- Procedures over answers: teach the approach that generalizes, with one
+  concrete worked example.
+- **Gotchas section** — often the highest-value part: concrete corrections to
+  mistakes the agent *will* make ("the /health endpoint lies; use /ready").
+- For multi-step workflows: an explicit checklist. For fragile output: a
+  template (agents pattern-match better than they follow prose). For
+  correctness-critical work: a validation loop (do → validate → fix → repeat)
+  or plan-validate-execute with a validator script.
+
+**Scripts**: when you see an agent reinventing the same logic across runs,
+write it once, test it, bundle it in `scripts/`, and reference it from the
+body with exact invocations. Prefer zero-dependency scripts; pin versions for
+`npx`/`uvx` one-offs. Scripts should print errors an agent can self-correct
+from ("field X not found — available: a, b, c").
+
+## Evaluating (before trusting)
+
+- **Trigger check**: draft ~10 realistic prompts that *should* fire the skill
+  (varied phrasing, some not naming the domain) and ~10 near-misses that
+  *shouldn't* (share keywords, need something else). Run them; the skill
+  triggered if its body was loaded. Fix the description, not the body, for
+  trigger failures.
+- **Output check**: run 2-3 real tasks **with and without** the skill. If
+  with-skill isn't clearly better, the skill isn't earning its context — cut
+  or sharpen it. Read execution traces, not just outputs: wasted steps mean
+  vague instructions, inapplicable instructions being followed, or menus
+  without defaults.
+
+## Maintaining
+
+- **Every correction is a candidate gotcha.** When a human (or reviewer)
+  corrects an agent following the skill, add the correction to the gotchas —
+  this is the single best maintenance loop.
+- Treat skills like code: prune on every edit; if the agent ignores a rule,
+  the skill is probably too long and the rule is drowning. Test behavior
+  changes by observing runs, not by rereading the text.
+- Never let a skill grow past one coherent unit of work — split like you'd
+  split a function.
+- Log skill changes in the soul's `knowledge/log.md` (`**Update**: skills/x —
+  added gotcha about …`) so knowledge history and skill history stay one
+  timeline. Knowledge maintenance and skill maintenance are the same duty:
+  declarative lessons go to OKF concepts, procedural lessons go to skills,
+  and each should link to the other.

package/skills/soul-craft/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: soul-craft
+description: >-
+  How to author and maintain an agent's soul — its AGENTS.md/CLAUDE.md
+  operating doc, soul.yaml config, and the balance between AGENTS.md, skills,
+  and the OKF knowledge base. Use when creating a new agent (writing its first
+  AGENTS.md), refining an existing soul that underperforms (agent ignores
+  instructions, drifts from its role, bloated operating doc), reviewing a
+  soul's setup, or deciding what goes in AGENTS.md versus a skill versus
+  knowledge. Based on the agents.md standard and Anthropic CLAUDE.md guidance.
+---
+
+# Soul craft — author and maintain agent operating docs
+
+A soul's `AGENTS.md` is loaded **every session of
+every instance**. It is the most expensive real estate in the agent's context:
+everything in it taxes every task, relevant or not. The craft is keeping it
+minimal and pushing everything else to on-demand layers.
+
+**Canonical files:** `AGENTS.md` and `.agents/skills/` are the canonical
+sources; `CLAUDE.md` and `.claude/skills` must always be relative symlinks to
+them, never independent files (the spawner creates these links — if you find a
+real CLAUDE.md file diverging from AGENTS.md, that's a defect: merge and relink).
+
+## The three-layer rule
+
+| Layer | Loaded | Belongs there |
+|---|---|---|
+| **AGENTS.md** | always | Role, boundaries, the default workflow, memory pointers — only what applies to *every* session |
+| **skills/** | on demand (description match) | Domain workflows, repeatable procedures ("how") — see `skill-craft` |
+| **knowledge/** | on demand (index-first) | Facts, decisions, lessons ("what/why") — format per the knowledge integration (default okf) |
+
+The test for every AGENTS.md line: **"would removing this cause mistakes in
+most sessions?"** No → move it to a skill or a knowledge concept, or cut it.
+Bloated operating docs cause agents to ignore the rules that matter — a rule
+being ignored is usually a symptom of too many rules.
+
+## Writing a soul's AGENTS.md
+
+Structure that works (keep the whole thing short — a screen or two):
+
+1. **Role, one paragraph.** Who this agent is, what it owns, where it stops.
+   Boundaries beat capabilities: "you never merge", "you never modify the
+   assignee", "UI belongs to the ui agent" prevent more damage than feature
+   lists add value.
+2. **Operating loop.** The default shape of a work session — for a developer:
+   read ticket → plan in STATE.md → implement in ./work → verify → commit →
+   review loop → hand off. Concrete, not aspirational.
+3. **Verification.** How this agent checks its own work: the build/test/lint
+   commands that must pass, what "done" means. An agent with a check it can
+   run closes its own loop; without one, "looks done" is the only signal.
+   Include exact commands the agent can't guess (`make test-unit`, not
+   "run the tests").
+4. **Memory pointers.** Where its knowledge and state live (knowledge base
+   index, STATE.md discipline). Point, don't duplicate — the protocol lives
+   with your knowledge integration (default okf: the memory-harvest skill).
+5. **Escalation.** When to stop and ask the human or coordinator: the
+   human-gate triggers (security, authz, migrations, contract breaks),
+   plus "report to your spawner, don't self-fix" for infrastructure faults.
+
+Style rules (from the agents.md standard + field experience):
+- Write commands, not prose: `pnpm vitest run -t "<name>"` beats "run the
+  relevant test".
+- Include only what can't be inferred from the repo: conventions that differ
+  from defaults, env quirks, etiquette (branch naming, PR format).
+- Exclude: standard language conventions, file-by-file codebase tours, API
+  docs (link instead), anything that changes weekly (that's knowledge),
+  self-evident advice ("write clean code").
+- Emphasis (**IMPORTANT**, YOU MUST) sparingly — it works, and it stops
+  working when everything is emphasized.
+- The repo's own AGENTS.md (in ./work) covers repo mechanics — the soul doc
+  covers the *role*. Don't duplicate the repo doc; instruct reading it.
+
+## soul.yaml
+
+Keep honest: `repo` (what it works on), `work` (worktree for builders,
+checkout for reviewers/coordinators), `runtime`, `model` (only pin when the
+role needs a specific one — reviewers on a different model than authors),
+`description` (one line; shows in rosters and pickers).
+
+## Maintaining a soul
+
+- **Change AGENTS.md rarely and deliberately** — it defines the agent. The
+  bar: a change in how the agent fundamentally operates, proven by instance
+  experience. Day-to-day lessons go to knowledge; procedures to skills.
+- When an instance repeatedly misbehaves, diagnose in order: (1) is the rule
+  drowning in a bloated doc? → prune the doc; (2) is it ambiguous? → sharpen
+  with a command or example; (3) is it missing? → add it, minimally. Test by
+  observing the next instance's behavior, not by rereading.
+- **Prune on every edit.** Adding a line? Look for two to cut.
+- Log every soul change in `knowledge/log.md` (`**Update**: AGENTS.md — …`)
+  so the soul's evolution is reconstructible.
+- Agents never rewrite their own role or safety boundaries; soul changes that
+  alter behavior go through the human (or a documented review workflow).
+- Periodic review (worth doing when spawning feels off): does the role still
+  match reality? Do skills cover the recurring procedures? Is the knowledge
+  index current? Are the verification commands still correct?
+
+## Bootstrapping a new soul
+
+Fastest path to a *grounded* soul (never write one from imagination):
+1. Do (or supervise) the role's work once in a plain session, noting
+   corrections, commands, and conventions as you go.
+2. Distill: role/boundaries/loop/verification/escalation → AGENTS.md;
+   repeated procedures → first skills; facts and decisions → first knowledge
+   concepts.
+3. Spawn an instance on a real task; watch where it stumbles; fold the
+   corrections back (doc, skill gotcha, or concept — per the three-layer rule).
+Two rounds of this beat any amount of upfront authoring.