AI Workflows
Specifications
Skills vs Docs
- Skills (
skills/<name>/SKILL.md) = executable agent instructions. How to do things (conventions, workflows, tool usage)
- Docs (
docs/) = project documentation. What was decided and why (rfcs/, guides/, plans/, runbooks/, architecture/)
- Both exist in every project; neither replaces the other
- Every repo should also have: README.md (humans) + AGENTS.md (AI) + llms.txt (LLM discovery)
- Root-level standard files (README, AGENTS.md, CONTRIBUTING, LICENSE, CODEOWNERS, llms.txt) stay at root; everything else goes in
docs/
AI Tools
| Tool |
Usage |
| Claude Code (opus) |
Primary AI coding assistant. Architecture, refactoring, multi-file edits |
| OpenAI Codex |
workspace-write "Auto" base config with a guardian auto-reviewer; ships writer, reviewer, plan, and guardian profiles/agents |
| Google Antigravity CLI (agy) |
Replaces legacy Gemini CLI; per-command allow/deny lists managed in-app via /permissions, --sandbox for terminal restrictions |
| GitHub Copilot |
Inline completion plus settings.json (model, reasoning effort, theme) |
Claude Code Configuration
Claude Code is configured per-project via CLAUDE.md files at the repository root. These files define:
- Project context tech stack, directory structure, key patterns
- Coding conventions naming, formatting, commit style
- Behavioral rules what to avoid, how to handle edge cases
- Memory persistent notes stored in
.claude/ directories
Best Practices
- Keep
CLAUDE.md concise; it's loaded into every conversation
- Use separate memory files for detailed topic notes
- Reference project-specific tools and commands
- Define verification steps (build, test, lint)
AGENTS.md Standard
Every repo MUST have AGENTS.md at root.
Template Structure
- Identity project name, one-line description
- Architecture high-level component overview
- Commands build, test, lint, run
- Code Style language-specific conventions
- Extension Guide how to add features
Do NOT include static directory trees or file tables; structure goes stale. Instead, instruct agents to use tree and ripgrep/ag to discover project layout on the fly.
Skills Standard
Every repo with a CLI or library should have skills/<name>/SKILL.md:
- Frontmatter:
name, description, argument-hint (for CLI tools)
- Content: step-by-step guidance for using or extending the project
- Skills live in
skills/<name>/SKILL.md within each repo
Git Workflows
AI-assisted commit, review, and PR authoring live in dedicated agent skills (ship, pr, review), not in the release tool. The release tool (sr) is release-engineering only as of v7: release, status, config, init, migrate, completions, update. See sync-release for release conventions and sr migrate for the upgrade guide from older versions.
Source: urmzd/dotfiles — distributed by TomeVault.
1---2name: configure-ai3description: Authors AGENTS.md and defines the skills-vs-docs boundary for a repo. Configures AI coding tools (Claude Code, Codex, Antigravity CLI, Copilot) and the skills-as-docs philosophy. Use when creating or auditing AGENTS.md, setting up AI tooling for a project, or deciding what belongs in a skill versus docs/. Do NOT use for README structure -> use write-readme; for llms.txt generation -> use create-llms-txt; for Claude-specific skill features (invocation control, subagents, model overrides) -> use extend-oss-skills-to-claude. Use when this capability is needed.4---56# AI Workflows78## Specifications910| Convention | Spec |11|------------|------|12| SKILL.md | [Agent Skills Specification](https://agentskills.io/specification) |13| AGENTS.md | [agents.md Standard](https://agents.md/) |14| llms.txt | [llms.txt Specification](https://llmstxt.org/) |1516## Skills vs Docs1718- **Skills** (`skills/<name>/SKILL.md`) = executable agent instructions. *How to do things* (conventions, workflows, tool usage)19- **Docs** (`docs/`) = project documentation. *What was decided and why* (rfcs/, guides/, plans/, runbooks/, architecture/)20- Both exist in every project; neither replaces the other21- Every repo should also have: README.md (humans) + AGENTS.md (AI) + llms.txt (LLM discovery)22- Root-level standard files (README, AGENTS.md, CONTRIBUTING, LICENSE, CODEOWNERS, llms.txt) stay at root; everything else goes in `docs/`2324## AI Tools2526| Tool | Usage |27|------|-------|28| Claude Code (opus) | Primary AI coding assistant. Architecture, refactoring, multi-file edits |29| OpenAI Codex | `workspace-write` "Auto" base config with a guardian auto-reviewer; ships writer, reviewer, plan, and guardian profiles/agents |30| Google Antigravity CLI (agy) | Replaces legacy Gemini CLI; per-command allow/deny lists managed in-app via `/permissions`, `--sandbox` for terminal restrictions |31| GitHub Copilot | Inline completion plus `settings.json` (model, reasoning effort, theme) |3233## Claude Code Configuration3435Claude Code is configured per-project via `CLAUDE.md` files at the repository root. These files define:3637- **Project context** tech stack, directory structure, key patterns38- **Coding conventions** naming, formatting, commit style39- **Behavioral rules** what to avoid, how to handle edge cases40- **Memory** persistent notes stored in `.claude/` directories4142### Best Practices4344- Keep `CLAUDE.md` concise; it's loaded into every conversation45- Use separate memory files for detailed topic notes46- Reference project-specific tools and commands47- Define verification steps (build, test, lint)4849## AGENTS.md Standard5051Every repo MUST have `AGENTS.md` at root.5253### Template Structure54551. **Identity** project name, one-line description562. **Architecture** high-level component overview573. **Commands** build, test, lint, run584. **Code Style** language-specific conventions595. **Extension Guide** how to add features6061Do NOT include static directory trees or file tables; structure goes stale. Instead, instruct agents to use `tree` and `ripgrep`/`ag` to discover project layout on the fly.6263## Skills Standard6465Every repo with a CLI or library should have `skills/<name>/SKILL.md`:6667- **Frontmatter:** `name`, `description`, `argument-hint` (for CLI tools)68- **Content:** step-by-step guidance for using or extending the project69- Skills live in `skills/<name>/SKILL.md` within each repo7071## Git Workflows7273AI-assisted commit, review, and PR authoring live in dedicated agent skills (`ship`, `pr`, `review`), not in the release tool. The release tool (`sr`) is release-engineering only as of v7: `release`, `status`, `config`, `init`, `migrate`, `completions`, `update`. See `sync-release` for release conventions and `sr migrate` for the upgrade guide from older versions.7475---76> Source: [urmzd/dotfiles](https://github.com/urmzd/dotfiles) — distributed by [TomeVault](https://tomevault.io).77<!-- tomevault:4.0:skill_md:2026-06-16 -->