# Agent Md Expert

> Expert guidance for creating, auditing, and maintaining minimal, cache-friendly, and structure-decoupled context files (AGENTS.md and CLAUDE.md). Trigger this skill when the user mentions context files, repo rules, agents.md, claude.md, prompt optimization, or wants to check agent instructions.

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

## Install

```sh
agentstack add skill-josephsanjaya-skills-agent-md-expert
```

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

## About

# Agent MD Expert

Expert guide to build, audit, and maintain minimal, cache-aligned repository context files (AGENTS.md / CLAUDE.md). Cut token usage while boosting success rate.

Minimize context files ruthlessly. Place static content at start, dynamic variables at end to preserve prefix caching. Eliminate duplicate files/overviews. Use python validator to check constraints.

## 1. Decision Matrix

| Task / Context | Action | Reference |
| :--- | :--- | :--- |
| **Analyze / Audit context file** | Run Python lint script | [scripts/validate_agent_md.py](file:///Users/jsanjaya/Projects/skills/agent-md-expert/scripts/validate_agent_md.py) |
| **Cache & Alignment optimization** | Static-first layout; append-only | [references/caching-and-positioning.md](file:///Users/jsanjaya/Projects/skills/agent-md-expert/references/caching-and-positioning.md) |
| **Pruning redundancy** | Remove overviews, linters, standard rules | [references/minimization-and-redundancy.md](file:///Users/jsanjaya/Projects/skills/agent-md-expert/references/minimization-and-redundancy.md) |
| **Monorepo setup (Spine + Leaf)** | Root Spine rules + subdir Leaf overrides | [references/monorepo-spine-leaf.md](file:///Users/jsanjaya/Projects/skills/agent-md-expert/references/monorepo-spine-leaf.md) |

---

## 2. Core Rules

- **No directory overviews:** Delete all folder trees and architecture lists. Agents discover files automatically via tools.
- **Zero redundancy:** Never duplicate README, CONTRIBUTING, or configs (e.g. package.json). Redundancy reduces success rate by 3% and raises costs 20%+.
- **Keep it short:** Target 

---

## 3. Auditing Workflow

1. Run the Python validator script:
   ```bash
   python3 /Users/jsanjaya/Projects/skills/agent-md-expert/scripts/validate_agent_md.py 
   ```
2. Review issues (HIGH/MEDIUM/LOW) and trim the file.
3. Replace descriptive paragraphs with direct, imperative bullet lists.
4. Ensure no information duplicates the project's existing Markdown files.

---

## 4. Samples

*   [Spine (Root) Template](file:///Users/jsanjaya/Projects/skills/agent-md-expert/samples/spine-agents.md) — Base root configuration.
*   [Leaf (Subdir) Template](file:///Users/jsanjaya/Projects/skills/agent-md-expert/samples/leaf-agents.md) — Directory-specific Electron/IPC constraints.

- Outputs must conform only to the validation rules.
- You should run the python validation script on all edited context files.
- The output format must be minimal and under 800 words.

Target Path: {target_path}
Dynamic Inputs: {dynamic_inputs}

## Source & license

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

- **Author:** [JosephSanjaya](https://github.com/JosephSanjaya)
- **Source:** [JosephSanjaya/skills](https://github.com/JosephSanjaya/skills)
- **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-josephsanjaya-skills-agent-md-expert
- Seller: https://agentstack.voostack.com/s/josephsanjaya
- 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%.