# Agents Md

> Generate or refresh the workspace-root AGENTS.md and its CLAUDE.md redirect shim for a VS Code .code-workspace root. Any request to write, create, or generate an AGENTS.md file routes here — /writing-for-agents is style guidance for authoring agent-facing documents, not the generator. It creates the Project Matrix of PROJECT-CODEs and the workspace's non-negotiable rules. Use when establishing, b…

- **Type:** Skill
- **Install:** `agentstack add skill-devarfeen-agent-skills-kit-agents-md`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [devarfeen](https://agentstack.voostack.com/s/devarfeen)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [devarfeen](https://github.com/devarfeen)
- **Source:** https://github.com/devarfeen/agent-skills-kit/tree/main/skills/agents-md

## Install

```sh
agentstack add skill-devarfeen-agent-skills-kit-agents-md
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AGENTS.md generator

Turns one `.code-workspace` file plus a small scan of its folders — nothing else — into the workspace-root `AGENTS.md` and its `CLAUDE.md` redirect shim.

## Inputs

- The target root must contain a `*.code-workspace` file (multi- or single-folder). If none exists, stop and do not generate files — the Project Matrix is built from its `folders` list; tell the user to rerun from a folder holding one.
- Never read or copy the agent's own global or user instruction files (`~/.claude/CLAUDE.md`, `~/.codex/`, global `AGENTS.md`, personal memory/rules) — no personal rule (co-author, memory, context, issue-routing) may appear in the generated files.

## Rules

- `AGENTS.md` is the single source of truth for Codex CLI, Claude CLI, Antigravity CLI, Cursor CLI, Opencode CLI, and GitHub Copilot CLI; all operating instructions — context, memory policy, issue routing, skill use — live there.
- `CLAUDE.md` is only a redirect shim for Claude CLI: emit [`assets/claude-md-template.md`](assets/claude-md-template.md) byte-for-byte, nothing more, and never read other context from it.
- Generate exactly one of each, at the workspace root — never per-project or per-repo `AGENTS.md`. The generated `AGENTS.md` is spartan and direct.

## Workspace scan

Small-scan every workspace folder before generating: note any `VISION.md`/`vision.md` at the workspace or a project root (feeds North star) and detect each stack. Multiple stacks → the intro slot says so and warns against mixing conventions or code across projects.

### Stack detection

The `Stack` cell is fact read from the app-root manifest and lockfiles — never guessed from a folder's name, a root-level manifest, or a file's mere existence.

- **Find the real app root** — often nested (`application/`, `app/`, `src/`); read the manifest there and note the dir.
- **PHP** — `composer.json`: version from `require.php`, frameworks from `require`; CodeIgniter version from `system/core/CodeIgniter.php` `CI_VERSION`. A Livewire app must say Livewire.
- **Frontend build** — list `Vite`/`Tailwind` only when `vite`/`laravel-vite-plugin`/`tailwindcss` are in the app's own `package.json` deps; Laravel never implies one.
- **JS / TS** — `package.json`: runtime + version; `TypeScript` when a `typescript` dep or `tsconfig.json` exists; package manager from the lockfile (`package-lock.json` → npm, `yarn.lock` → yarn, `pnpm-lock.yaml` → pnpm).
- **Python** — framework from `requirements.txt` / `pyproject.toml`; version from `Dockerfile` `FROM python:X.Y`, `.python-version`, or `requires-python`.
- **A test runner is not the stack**; name one only when there is no app framework.
- **Non-app folders** — `"type": "library"` in `composer.json` (or no app framework) means a package, noted `VCS, branch ` when branch-installed; raw SQL/migration folders are " / raw SQL migrations"; the `.`-path folder is a meta workspace, not a code stack.

## Project Matrix format

One row per `.code-workspace` folder, in `folders` order — never invent or drop projects. Columns exactly `| Project | Path | Stack |`:

- `Project`: the PROJECT-CODE from the folder `name` — strip emojis, uppercase, collapse punctuation/space runs to single hyphens, trim leading/trailing hyphens (`Payments API` → `PAYMENTS-API`); path basename when `name` is missing; type prefix for non-app folders (`PACKAGE-QUEUE`, `DB`). Name the full PROJECT-CODE from the Project Matrix everywhere; never mix one project's conventions, tokens, or components into another.
- `Path`: the folder `path` relative to the workspace root; `.` marks the meta/workspace row.
- `Stack`: one terse line — language, every primary framework, build tooling, package manager; versions only when a manifest pins them; non-app folders state the role. No prose in cells.

Sample:

```markdown
| PAYMENTS-API | ../payments-api  | PHP 8.3 / Laravel 13 / Vite / Composer + npm (application/) |
| DB           | ../db-migrations | MySQL / raw SQL migrations |
```

## Emitted skeleton

Emit [`assets/agents-md-template.md`](assets/agents-md-template.md) byte-for-byte, filling only the bracketed slots (intro line, Project Matrix, skills tables + startup note, `### Runtime Tool-Calling` tables, and the `### North star` list when emitted). Three rules bind the verbatim parts:

- Emit `### Matt Skill Routing` only when Matt Pocock's skills are installed (`/ask-matt`, `/grill-with-docs`, or `/to-spec` resolves); otherwise delete the subsection — dead routing rules cost every session tokens.
- Emit `### North star` only when the scan found a vision file, listing each with its scope; never fabricate one or restate its content — the subsection points at the file. None found → delete it.
- Keep `Issue Titles` exactly as concise as the skeleton has it — routing/label procedure lives in the issue skills, never here — and leave the two Context & Native Memory placeholders unfilled.

## Working with skills

Generate the gradient and companion tables from `references/skills-manifest.md` — the single source; adding or moving a skill edits the manifest, never this file. Column semantics live in its header; `kit` and `external` skills render alike.

Fill the `[RUNTIME TOOL-CALLING …]` slot from `references/tool-calling.md`, opening a per-runtime `*-tools.md` only when a cell is missing or unclear. Emit three compact tables — skill invocation, parallel/background mechanism (drop the `Custom agent files` column), and highest elevated launch preset per runtime — inlined; never link the reference files (they do not ship) or restate the Local Orchestration rule. The elevated table must say those presets are used only when the user explicitly asks for highest/elevated/full/YOLO permission and prefers an isolated container, VM, dev container, or disposable worktree.

## Versioning and regeneration

The skill version is `v15`. Both generated files carry the marker `` as their first line (the first line of each template asset in `assets/`). Bump it here and in both template assets together whenever these rules change. Pre-`v6` files open with the older `Generated by the agents-md skill` comment — still a valid marker, not hand-authored.

On run, check for an existing workspace-root `AGENTS.md`:

- **None** — generate fresh.
- **Marker present** — before overwriting, show a short diff (changed lines only) and confirm. If the user does not respond, stop without writing and say so.
- **No marker (hand-authored)** — do not rewrite it; show what generation would add or change, merge only user-approved sections, and let the existing file win everywhere else.
- **Preserve user edits** — carry over every user-filled placeholder value (especially the `CONTEXT.md` and `specs/adr` paths) and per-project on-demand reads.
- **Preserve foreign sections** — carry over verbatim any section another skill added (e.g. `## Design System / UI Library` from /design-system); regeneration replaces only sections this skill generates.
- Regenerate the `CLAUDE.md` shim only if it is missing or its marker is stale.

### Migrate docs/ → specs/ (ask first)

Pre-v7 workspaces kept the artifacts tree under `docs/` instead of `specs/`. When any artifact subfolder (`agents/`, `adr/`, `prompts/`, `qa/`, `port/`, `pixel-audit/`, `integration/`, `design-system/`, `release-notes/`) still sits under `docs/` — strays included — show what would move and ask first; declined or no response → keep the `docs/` paths, never rename unattended. On approval, `git mv` per subfolder (plain `mv` when untracked), merging file by file into any existing `specs//` — never `git mv docs specs` wholesale. Rewrite `docs//` links to `specs//` in the moved files and any file linking them, update filled placeholder paths, and report every move. Non-artifact `docs/` content (the GitHub Pages site) stays.

## Output

Chat carries the pre-write diff, the migration move list and report, and the close: suggest `/setup-matt-pocock-skills`, and `/design-system` for each UI project, then stop — suggest only, never run them.

## Completion criteria

- [ ] `AGENTS.md` sections appear in template order; `### Matt Skill Routing` present only when Matt's skills resolve, `### North star` only when a vision file was found
- [ ] Regeneration: foreign sections and user-filled values survive in the shown diff — or the run stopped without writing

- [ ] Project Matrix row count equals the `folders` count; every Stack cell traces to a manifest actually read
- [ ] Both generated files open with the current version marker; Context & Native Memory placeholders intact or carried over filled
- [ ] `diff` of `CLAUDE.md` against the shim template is empty
- [ ] Post-migration: `docs/` holds only the GitHub Pages site; no moved artifact still links a `docs/` path
- [ ] Neither file leaks session data: dates, conversation references, machine-local absolute paths

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [devarfeen](https://github.com/devarfeen)
- **Source:** [devarfeen/agent-skills-kit](https://github.com/devarfeen/agent-skills-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-devarfeen-agent-skills-kit-agents-md
- Seller: https://agentstack.voostack.com/s/devarfeen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.