# Agentsmd Scaffold

> Generate or update repository-specific AGENTS.md instruction files from real repo evidence. Use when asked to create, design, scaffold, split, or improve root or scoped AGENTS.md files for Codex/Claude/agent workflows, especially when a repo needs directory-specific rules, validation commands, generated-file boundaries, or a short agent onboarding router.

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

## Install

```sh
agentstack add skill-majiayu000-spellbook-agentsmd-scaffold
```

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

## About

# AGENTS.md Scaffold

Use this skill to generate a small, evidence-backed `AGENTS.md` stack for a
repository. The output may be a plan, exact proposed file contents, or applied
files when the user explicitly asks to write them.

This skill is for instruction scaffolding. Use `repo-agent-context-audit` first
when the user only asks whether the repo's agent context is healthy.

## Operating Contract

Default to a scoped plan before editing. Only write or modify `AGENTS.md`,
`CLAUDE.md`, `WARP.md`, hooks, settings, or generated docs when the user has
explicitly asked to apply the scaffold.

Direct actions:
- Run read-only discovery, scanner commands, and repo command inspection.
- Produce a scoped `AGENTS.md` plan with evidence and validation commands.
- Draft exact file contents when the user asks for proposed text.

Escalate before:
- Creating or editing high-context files when the user only asked for an audit.
- Rewriting existing `AGENTS.md`, `CLAUDE.md`, or `WARP.md` instead of adding a
  short pointer or scoped complement.
- Batch-normalizing multiple repositories.

Evidence-backed pushback:
- Challenge new scoped files when the directory has no distinct local rules.
- Challenge guessed commands, ownership, or generated-file rules unless repo
  evidence supports them.

Feedback loop:
- Promote repeated false starts into `references/scaffold-agents.md`, scanner
  signals, or eval prompts.

## Workflow

### 1. Discover Existing Context

Run the scanner from this skill directory when possible:

```bash
python3 scripts/scan_repo_context.py 
python3 scripts/scan_repo_context.py  --json
```

Then inspect the files that matter:

- existing `AGENTS.md`, `CLAUDE.md`, `WARP.md`, `.claude/instructions.md`, and
  `.github/copilot-instructions.md`
- `README.md`, `CONTRIBUTING.md`, package manifests, Makefiles, CI workflows,
  and documented test commands
- generated files and their generators
- high-risk directories such as migrations, deploy scripts, auth, secrets,
  payments, registry metadata, generated clients, and production operations

Do not infer commands or ownership from names alone. Use scanner output as a
lead, then verify with actual files.

### 2. Choose The Instruction Stack

Read `references/scaffold-agents.md` before proposing files. Choose the
smallest stack that changes agent behavior:

- root `AGENTS.md` for repo-wide routing and validation
- nested `AGENTS.md` only where directory rules differ from root
- no nested file for directories that only need ordinary README context
- no bulk normalization across multiple repos until a few examples have been
  manually validated

### 3. Produce A Candidate Plan

Before editing, report:

```markdown
## Scoped AGENTS Plan

| Path | Why here | Rules to include | Validation |
|---|---|---|---|
| `AGENTS.md` |  |  | `` |
| `/AGENTS.md` |  |  | `` |

## Files To Preserve

- `` - 

## Open Facts

- 
```

### 4. Scaffold On Request

When applying the scaffold:

- keep root files short, normally 80-150 lines
- keep nested files focused on that directory's ownership, source-of-truth
  rules, and validation commands
- include real commands and paths, not placeholders, unless the fact is truly
  missing
- preserve existing high-context files unless the user requested a rewrite
- pair every prohibition with a concrete alternative, helper, generator, or
  command

## Decision Gates

| Situation | Action |
|---|---|
| Existing `CLAUDE.md` or `WARP.md` is already a good router | Add a short `AGENTS.md` pointer only if cross-runtime routing helps. |
| Root instruction file exceeds roughly 200 lines | Propose root router plus scoped files or references. |
| Directory has generated outputs | Add scoped rules naming source of truth and regenerate/check commands. |
| Directory has distinct safety rules | Add scoped rules with escalation boundaries. |
| Directory has ordinary implementation files only | Keep guidance in root unless conventions differ. |
| Commands cannot be verified from repo evidence | Leave an open fact instead of guessing. |

## Gotchas

- Do not add nested `AGENTS.md` files for every directory. Add them only where
  local rules differ from root.
- Do not guess build, test, lint, or generator commands from framework names.
  Cite the manifest, CI workflow, script, or docs that prove the command.
- Do not overwrite an existing `CLAUDE.md`, `WARP.md`, or `AGENTS.md` just to
  normalize naming. Preserve it, point to it, or propose a split first.
- Do not put long architecture explanations in root `AGENTS.md`; route to
  references or existing docs instead.

## Verification

After applying changes:

- run the repo's narrow validation command for the affected scope
- run any repo-wide registry, docs, typecheck, lint, or test command named in
  the new instructions when practical
- rerun `python3 scripts/scan_repo_context.py ` if using the bundled
  scanner to confirm scoped files are discoverable

If verification cannot run, report the exact missing precondition and the
command that should be run later.

## Resources

- `scripts/scan_repo_context.py`: read-only scanner for high-context files,
  command hints, specs, local skills, and scoped `AGENTS.md` candidates.
- `references/scaffold-agents.md`: scaffold selection rules and templates for
  root, generated metadata, scripts/tools, skill libraries, and tests.
- `evals/evals.json`: lightweight prompts for future behavior checks.

## Source & license

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

- **Author:** [majiayu000](https://github.com/majiayu000)
- **Source:** [majiayu000/spellbook](https://github.com/majiayu000/spellbook)
- **License:** MIT
- **Homepage:** https://github.com/majiayu000/spellbook#quick-start

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-majiayu000-spellbook-agentsmd-scaffold
- Seller: https://agentstack.voostack.com/s/majiayu000
- 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%.