agents md author

Documentation Community

Skill notes

When to activate

User asks to "write AGENTS.md", "create CLAUDE.md", or "set up project instructions for AI" User wants the same project doc to work in Codex, Claude Code, Cursor, or any tool that follows the AGENTS.md convention User mentions onboarding a new AI tool to an existing repo and wants conventions captured

1. Detect project context (always do this first)

Read the project root and determine: Project name — from package.json name, pyproject.toml [project].name, go.mod module, Cargo.toml [package].name, or fallback to repo dir name Language & runtime — package.json (Node + lockfile flavor), requirements.txt / pyproject.toml (Python), go.mod (Go), Cargo.toml (Rust), pom.xml / build.gradle (JVM), *.csproj (.NET) Common scripts — Node scripts.{dev,build,test,lint,typecheck}; Python tox.ini / Makefile; Go/Rust task tools

2. Decide the target file(s)

User wants · Write Codex / OpenAI tools only · AGENTS.md Claude Code only · CLAUDE.md Both, kept in sync · AGENTS.md + CLAUDE.md (identical content), or AGENTS.md plus a one-line CLAUDE.md that says "See AGENTS.md" Single source (recommended) · AGENTS.md + CLAUDE.md symlink → AGENTS.md

3. Compose content

Use this canonical structure (load references/agents-md-spec.md if you need the field-by-field rationale or cross-vendor details): Keep it under ~150 lines. AI agents skim — verbose docs are skipped or ignored.

4. Write files

Use canonical line endings for the OS (LF on macOS/Linux) Don't add a trailing summary or "generated by" footer — the file is now the user's If a file already exists, read it first, propose a diff, and ask the user before overwriting

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Documentation
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux
Runtime requirements
Node.js · Python
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# agents-md-author

Generate cross-vendor project instruction files: `AGENTS.md` for Codex (and most other tools), `CLAUDE.md` for Claude Code, or both kept in sync. Load `references/agents-md-spec.md` if you need the cross-vendor convention details.

## When to activate

- User asks to "write AGENTS.md", "create CLAUDE.md", or "set up project instructions for AI"
- User wants the same project doc to work in Codex, Claude Code, Cursor, or any tool that follows the AGENTS.md convention
- User mentions onboarding a new AI tool to an existing repo and wants conventions captured

## Procedure

### 1. Detect project context (always do this first)

Read the project root and determine:
- **Project name** — from `package.json` `name`, `pyproject.toml` `[project].name`, `go.mod` `module`, `Cargo.toml` `[package].name`, or fallback to repo dir name
- **Language & runtime** — `package.json` (Node + lockfile flavor), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go), `Cargo.toml` (Rust), `pom.xml` / `build.gradle` (JVM), `*.csproj` (.NET)
- **Common scripts** — Node `scripts.{dev,build,test,lint,typecheck}`; Python `tox.ini` / `Makefile`; Go/Rust task tools
- **Test framework** — vitest, jest, pytest, go test, cargo test, etc.
- **Repo conventions** — existing `.editorconfig`, `.prettierrc`, `eslint.config.*`, `pre-commit-config.yaml`

If the user provided context (e.g., "this is a Next.js + Prisma app"), use it; otherwise infer from files. Don't ask questions you can answer from disk.

### 2. Decide the target file(s)

| User wants | Write |
|---|---|
| Codex / OpenAI tools only | `AGENTS.md` |
| Claude Code only | `CLAUDE.md` |
| Both, kept in sync | `AGENTS.md` + `CLAUDE.md` (identical content), or `AGENTS.md` plus a one-line `CLAUDE.md` that says "See AGENTS.md" |
| Single source (recommended) | `AGENTS.md` + `CLAUDE.md` symlink → `AGENTS.md` |

Default to "both, identical content" unless the user specifies — it's the lowest-risk option and works everywhere.

### 3. Compose content

Use this canonical structure (load `references/agents-md-spec.md` if you need the field-by-field rationale or cross-vendor details):

```markdown
# <Project name>

<one-sentence description>

## Tech stack

- <language + version>
- <framework + version>
- <database / runtime / deployment>

## Dev commands

- Install: `<command>`
- Dev server: `<command>`
- Build: `<command>`
- Test: `<command>` (unit) / `<command>` (e2e)
- Lint / typecheck: `<command>`

## Code conventions

- <indent + line length>
- <import style>
- <naming conventions>
- <test colocation>
- <commit style>

## Architecture notes

<2-5 bullets on layout — where routes live, where business logic lives, what's shared>

## Out of scope for AI agents

<deliberate "don't touch" list — generated files, secrets, migrations, etc.>
```

Keep it under ~150 lines. AI agents skim — verbose docs are skipped or ignored.

### 4. Write files

- Use canonical line endings for the OS (LF on macOS/Linux)
- Don't add a trailing summary or "generated by" footer — the file is now the user's
- If a file already exists, **read it first**, propose a diff, and ask the user before overwriting

### 5. Verify

- Print the relative paths written
- If both `AGENTS.md` and `CLAUDE.md` were written, confirm they're byte-identical (or show the symlink)
- Suggest the user commit the files

## References

- `references/agents-md-spec.md` — full cross-vendor convention summary (Anthropic, OpenAI, Cursor, etc.) — load on demand for spec details, vendor matrix, and the AGENTS.md ≠ SKILL.md distinction
- Anthropic Agent Skills spec: https://github.com/anthropics/skills
- OpenAI Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md
- agents.md cross-vendor standard: https://agents.md

---
> Source: [anton-abyzov/vskill](https://github.com/anton-abyzov/vskill) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.