OpenClaw Agent Authoring

Use this skill when the job is designing or repairing OpenClaw behavioral markdown, not runtime config or generic documentation.

This skill is intentionally self-contained. Use the references in this folder, not repo-only notes, while doing the runtime work.

Install

npx skills add https://github.com/aelaguiz/authoring-skills.git -g -a codex -a openclaw --skill openclaw-agent-authoring -y

When to use

• The user wants a new OpenClaw agent workspace from scratch.
• An existing OpenClaw agent needs better file boundaries across AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, BOOTSTRAP.md, or BOOT.md.
• The user wants to decide what belongs in always-read bootstrap files versus lifecycle files, memory files, skills, or hooks.
• The user wants a findings-first audit of an OpenClaw agent's file layering, session-kind behavior, or memory layout.
• The user wants to refactor a bloated OpenClaw workspace so each file type does one job well.

When not to use

• The task is ordinary copy editing, summarization, or README writing rather than OpenClaw agent design.
• The job is only a reusable skill package or hook package divorced from a larger agent workspace; use skill-authoring unless the workspace-behavior boundary itself is the point.
• The work is runtime config, workspace routing, tool policy, or fleet shaping rather than behavioral markdown.
• The work is only live gateway operations or incident triage, not authoring.
• The existing workspace files cannot be inspected.

Non-negotiables

• Follow native OpenClaw semantics first and repo-local overlays second.
• Keep always-read injected files lean; if a procedure is specialized or optional, move it to a skill or hook.
• Give each surface one primary job. Do not collapse identity, operating contract, tool caveats, user profile, memory, and scheduling into one blob.
• Do not treat prose as enforcement. If the need is runtime policy rather than behavior markdown, it is out of scope for this skill.
• Never store secrets or the only copy of live workflow truth in behavior files.
• Author with session kind in mind: main session, subagent, cron/lightweight, heartbeat, and gateway startup do not behave the same way.
• Distinguish workspace-local files from shared layers and managed skills/hooks.
• If vendor source and public docs drift, prefer the stronger local reference pack bundled with this skill.

First move

1. Classify the job as author, edit, refactor, or audit.
2. Read references/agent-workspace-model.md.
3. Read the smallest additional references that match the surfaces in play:
   • references/core-bootstrap-files.md for AGENTS.md, SOUL.md, and TOOLS.md
   • references/identity-and-user-files.md for IDENTITY.md and USER.md
   • references/lifecycle-and-scheduling-files.md for BOOTSTRAP.md, BOOT.md, and HEARTBEAT.md
   • references/memory-files.md for MEMORY.md, memory.md, and memory/YYYY-MM-DD.md
   • references/skills-hooks-and-on-demand-surfaces.md for SKILL.md and HOOK.md
   • references/examples-and-anti-patterns.md when you need grounded examples or want to sanity-check file placement

Workflow

1. Lock the agent's job, users, session kinds, and ownership boundaries before touching wording.
2. Decide which behavior belongs in always-read bootstrap, lifecycle files, memory files, and on-demand skills or hooks.
3. Establish the always-read core first: SOUL.md, AGENTS.md, and TOOLS.md.
4. Add profile, lifecycle, memory, and on-demand surfaces only where they change execution quality.
5. Keep each file pointed at its own job and cut text that belongs in another surface.
6. Validate both file-level quality and cross-file composition before shipping.

Output expectations

• author: return or create the behavioral markdown package with the leanest viable file set and clear file boundaries.
• edit: patch the existing workspace markdown and briefly explain which surfaces changed and why.
• refactor: preserve useful behavior while redistributing content into the correct behavioral files.
• audit: return findings first. For each finding, state the problem, why it matters, and which file should change.

Reference map

• references/agent-workspace-model.md - native file catalog, load model, layering, and reading order
• references/core-bootstrap-files.md - AGENTS.md, SOUL.md, and TOOLS.md
• references/identity-and-user-files.md - IDENTITY.md and USER.md
• references/lifecycle-and-scheduling-files.md - BOOTSTRAP.md, BOOT.md, and HEARTBEAT.md
• references/memory-files.md - MEMORY.md, memory.md, and daily memory files
• references/skills-hooks-and-on-demand-surfaces.md - SKILL.md and HOOK.md
• references/examples-and-anti-patterns.md - grounded examples and misplacement patterns