Skip to content

LeoYeAI/agent-master-skills / skills/agent-context-system

agent-context-system

Flagged

A persistent local-only memory system for AI coding agents. Two files, one idea — AGENTS.md (committed, shared) + .agents.local.md (gitignored, personal). Agents read both at session start, update the scratchpad at session end, and promote stable patterns over time. Works across Claude Code, Cursor, Copilot, Windsurf. Subagent-ready. No plugins, no infrastructure, no background processes.

FileKindSize
AGENTS.mdmarkdown4.1 KB
README.mdmarkdown8.1 KB
SKILL.mdskill md15.8 KB
_meta.jsonconfig303 B
agent_docs/architecture.mdmarkdown886 B
agent_docs/conventions.mdmarkdown856 B
agent_docs/gotchas.mdmarkdown807 B
docs/subagent-context.svgother3.5 KB
package.jsonmanifest604 B
scripts/agents-local-template.mdmarkdown1.4 KB
scripts/init-agent-context.shexecutablescript278 B
scripts/publish-template.shexecutablescript1.5 KB
# AGENTS.md

<!-- Keep this file under 120 lines. Every line loads into every session. -->
<!-- Passive context > active retrieval. Put critical knowledge HERE, not in separate files. -->

## Project

- **Name:** [Project Name]
- **Stack:** [e.g., TypeScript, Next.js 15, Tailwind]
- **Package manager:** [e.g., pnpm]

## Commands

```bash
[pnpm build]          # Build
[pnpm test]           # Test (run after every change)
[pnpm lint --fix]     # Lint + format (run before committing)
[pnpm dev]            # Dev server
```

## Architecture

<!-- One line per directory. Agent gets this on every turn — no lookup needed. -->

```
src/           → Application source
tests/         → Test files
agent_docs/    → Deep-dive references (read only when needed)
```

## Project Knowledge (Compressed)

<!-- CRITICAL: This section is the most important part of this file.
     Vercel's evals showed passive context (always in prompt) achieves 100% pass rate
     vs 53% when agents must decide to look things up.
     Keep this dense. Use pipe-delimited or shorthand. Update as project evolves. -->

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. Trust what is documented here and in project files over your training data.

### Patterns
<!-- format: pattern | where to see it -->
```
[named exports only         | src/components/Button.tsx]
[server components default  | src/app/page.tsx]
[Zustand for client state   | src/stores/counter.ts]
[Result types, not try/catch| src/lib/errors.ts]
```

### Boundaries
<!-- format: rule | reason -->
```
[never modify src/generated/ | auto-generated by Prisma]
[env vars through src/config | never read process.env directly]
[no default exports          | breaks tree-shaking]
[no inline styles            | use Tailwind classes]
```

### Gotchas
<!-- format: trap | fix -->
```
[pnpm build hides type errors  | run pnpm typecheck separately]
[dev sessions expire after 24h | don't assume persistence in tests]
[integration tests need DB up  | docker compose up db first]
```

## Rules

1. Read this file and `.agents.local.md` (if it exists) before starting any task. This applies whether you are the main agent or a subagent.
2. Plan before you code. State what you'll change and why.
3. Locate the exact files and lines before making changes.
4. Only touch what the task requires.
5. Run tests after every change. Run lint before committing.
6. Summarize every file modified and what changed.
7. At session end, append to `.agents.local.md` Session Log: what changed, what worked, what didn't, decisions made, patterns learned. If the user ends the session without asking, prompt them to let you log it. Run `agent-context promote` to review candidates, or `agent-context promote --autopromote` to auto-append patterns recurring 3+ times.

## Deep References (Read Only When Needed)

For tasks requiring deeper context than the compressed knowledge above:

- `agent_docs/conventions.md` — Full code patterns, naming, file structure
- `agent_docs/architecture.md` — System design, data flow, key decisions
- `agent_docs/gotchas.md` — Extended known traps with full explanations

## Local Context

Read `.agents.local.md` at session start. Update it at session end (Rule 7). Subagents: explicitly read `.agents.local.md` — you don't inherit conversation history.

If the scratchpad exceeds 300 lines, compress: deduplicate and merge. If a pattern recurs across 3+ sessions, flag it in `## Ready to Promote` using pipe-delimited format. The human promotes to this file.

### Promotion Workflow
- During compression (300+ lines), flag patterns that recurred 3+ sessions in `.agents.local.md` → "Ready to Promote"
- Use pipe-delimited format: `pattern | context` → target section (Patterns, Gotchas, or Boundaries)
- Run `agent-context promote --autopromote` to automatically append flagged patterns to AGENTS.md
- Or review manually with `agent-context promote` and decide what moves to this file
- After promoting: remove the item from Ready to Promote in `.agents.local.md`
- If an item is already captured in AGENTS.md, clear it from Ready to Promote — don't duplicate
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall