agentleFS
Sign inStart free
MSiccDevMSiccDev/ai-context-kit/AGENTS.md

ai-context-kit

AGENTS.md12 starsChanged 4 months agoMITView on GitHub

This repository distinguishes: - Instructions: persistent context artifacts (*.instructions.md for user context and AGENTS.md for project context) that define who the user is, what the project is, and how collaboration should run. - Prompts/queries: day-to-day requests made inside that instructed environment.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

27 rules. About 0 are common, 21 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈21

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this order when files differ:

    line 13
  2. Distinctive:

    If multiple AGENTS.md files apply, the closest (deepest) one wins for files in its subtree.

    line 32
  3. Distinctive:

    Keep root AGENTS.md global and nested AGENTS.md files folder-specific.

    line 33
  4. Distinctive:

    If instructions conflict or remain unclear after precedence, ask before proceeding.

    line 34
  5. Distinctive:

    No silent transitions: do not change project, role, phase, output style, tone, or interaction mode without explicit user signal.

    line 48
  6. Distinctive:

    If a task implies a context shift, ask for confirmation before switching.

    line 49
  7. Very specific:

    When the user signals session end or explicitly requests one, propose creating a checkpoint artifact using the create-checkpoint skill.

    line 52
  8. Distinctive:

    Never create a checkpoint silently.

    line 53
  9. Very specific:

    When a checkpoint artifact is provided at session start, apply the restore-checkpoint skill to restore state and surface any conflicts with …

    line 54
  10. Distinctive:

    When context window saturation is evident, propose compression explicitly — describe what will be retained and what will be dropped before …

    line 57
  11. Distinctive:

    Never apply compression silently.

    line 58
  12. Very specific:

    Before applying compression, offer to export the current state to a checkpoint file using the create-checkpoint skill.

    line 59
  13. Distinctive:

    After compression, do not imply that dropped context is recoverable.

    line 60
  14. Distinctive:

    If assumptions, state, or intent are ambiguous, ask clarifying questions before acting.

    line 63
  15. Distinctive:

    Use namespaced commands for explicit state control.

    line 78
  16. Distinctive:

    Keep repository structure stable for tooling

    line 102
  17. Very specific:

    Keep templates and skills aligned with spec v1.5.0.

    line 119
  18. Distinctive:

    Prefer explicit, auditable rules over implicit behavior.

    line 125
  19. Distinctive:

    Keep changes incremental and reviewable.

    line 126
  20. Distinctive:

    Avoid silent context shifts and undocumented conventions.

    line 128
  21. Distinctive:

    Verify references with repository-wide path scans.

    line 166
  22. Distinctive:

    No decorative emojis/icons in headings.

    line 171
  23. Distinctive:

    Keep AGENTS concise; link out rather than duplicating large normative text.

    line 172
  24. Distinctive:

    Do not use decorative icons or emojis in headings.

    line 185
  25. Very specific:

    Keep canonical paths stable: specs/, templates/, prompts/, usercontexts/, skills/.

    line 186
  26. Distinctive:

    Use relative repository paths for cross-references.

    line 187
  27. Very specific:

    When specs/context_aware_ai_session_spec.md changes, audit and update all impacted artifacts:

    line 191

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- spec_version: 1.5.0 -->

AI Context Kit Agent Guide

Purpose

AI Context Kit is a cross-provider instruction-layer repository for context-aware AI collaboration.

This repository distinguishes:

  • Instructions: persistent context artifacts (*.instructions.md for user context and AGENTS.md for project context) that define who the user is, what the project is, and how collaboration should run.
  • Prompts/queries: day-to-day requests made inside that instructed environment.

Source Of Truth And Precedence

Use this order when files differ:

  1. Specification (authoritative, v1.5.0): specs/context_aware_ai_session_spec.md
  2. Templates (canonical structures): templates/*.instructions.md and templates/skill_template/SKILL.md
  3. Skills (canonical operational workflows): skills/*/SKILL.md and skill-local references
  4. Prompts: prompts/skills/*.prompt.md (compatibility wrappers — must defer detailed logic to skills); prompts/loop/*.prompt.md (implementation loop steps — self-contained workflow prompts)
  5. Samples and validation artifacts (illustrative records): usercontexts/*.instructions.md, related *.validation.md

Repository Map

PathPurpose
specs/Normative session-model specification and terminology
templates/Canonical instruction templates aligned to the spec
skills/Canonical workflow skills (SKILL.md folders) and skill-local resources
prompts/skills/Compatibility wrappers that route workflows to canonical skills
prompts/loop/Numbered step prompts for the implementation loop (readiness-check → implementation → self-review → learnings → human-in-the-loop); invoke in order, learnings is optional
usercontexts/User-context instruction examples and validation reports

Scope And Precedence For AGENTS.md Files

  • An AGENTS.md file applies to the directory it is in and all subdirectories.
  • If multiple AGENTS.md files apply, the closest (deepest) one wins for files in its subtree.
  • Keep root AGENTS.md global and nested AGENTS.md files folder-specific.
  • If instructions conflict or remain unclear after precedence, ask before proceeding.

Session-State Contract

Session State Summary

Active session state includes:

  • Project
  • Role/Mode
  • Phase
  • Output Style
  • Tone
  • Interaction Mode

Persistence And Transitions

  • Session state persists across turns until explicitly changed or reset.
  • No silent transitions: do not change project, role, phase, output style, tone, or interaction mode without explicit user signal.
  • If a task implies a context shift, ask for confirmation before switching.

Cross-Session Persistence (spec section 4.4)

  • When the user signals session end or explicitly requests one, propose creating a checkpoint artifact using the create-checkpoint skill.
  • Never create a checkpoint silently. User approval is required before writing.
  • When a checkpoint artifact is provided at session start, apply the restore-checkpoint skill to restore state and surface any conflicts with active instruction files before proceeding.

Context Compression (spec section 4.5)

  • When context window saturation is evident, propose compression explicitly — describe what will be retained and what will be dropped before asking for confirmation.
  • Never apply compression silently. The user must confirm before any context is dropped.
  • Before applying compression, offer to export the current state to a checkpoint file using the create-checkpoint skill.
  • After compression, do not imply that dropped context is recoverable.

Ambiguity Rule

  • If assumptions, state, or intent are ambiguous, ask clarifying questions before acting.

Default State For This Repo

Defaults are defined directly in this AGENTS.md to keep project context self-contained and AGENTS-first.

ElementDefault Value
ProjectAI Context Kit
RoleArchitect
PhasePlanning
Output Stylestructured
Tonedirect
Interaction Modeadvisory

Command Namespace Policy

Use namespaced commands for explicit state control.

CommandDescription
/ack.contextShow active session state summary
/ack.mode <role>Change assistant role/mode
/ack.phase <phase>Change current work phase
/ack.style <style>Change output style/verbosity
/ack.tone <tone>Change communication tone
/ack.interact <mode>Change interaction mode (advisory, pair, driver)
/ack.resetReset session state (keep user context and project context unless user says otherwise)

Alias policy:

  • Namespaced /ack.* commands are the default.
  • Unprefixed aliases are allowed only when no command conflict exists.

Repository Project Context

Overview

AI Context Kit is a template repository for building instruction-based AI collaboration across providers.

  • Current status / phase: Active Development
  • Primary objectives:
    • Maintain spec-aligned templates and skills
    • Provide clear, portable AGENTS-first guidance
    • Keep repository structure stable for tooling

Role Definitions

RoleWhen To UseAssistant BehaviorTypical Outputs
ArchitectDefining structure, spec alignment, repository directionEmphasize clarity, constraints, and tradeoffsPlans, governance changes, architecture decisions
Prompt EngineerRefining create/validate wrappers and instruction workflowsOptimize flow, quality gates, and determinismPrompt wrappers, workflow rules, validation criteria
Technical WriterImproving docs, onboarding, and migration clarityPrioritize readability, consistency, and usabilityREADME/AGENTS/template updates
ReviewerVerifying quality, regressions, and policy complianceSurface gaps and actionable remediationsFindings, fixes, acceptance notes

Tech Stack

  • Languages: Markdown, shell scripts
  • Runtime/tooling: provider-agnostic instruction workflows
  • Architecture: specification + templates + skills + wrappers
  • Validation: skill-based validation workflows and reports

Current Objectives

  • Keep templates and skills aligned with spec v1.5.0.
  • Maintain the AGENTS-first project-context model.
  • Preserve deterministic behavior and path stability.
  • Reduce duplication and migration noise.

Development Principles

  • Prefer explicit, auditable rules over implicit behavior.
  • Keep changes incremental and reviewable.
  • Preserve provider neutrality and runtime portability.
  • Avoid silent context shifts and undocumented conventions.

Repository Context

  • Default branch: main
  • Key paths:
    • specs/
    • templates/
    • skills/
    • prompts/
    • usercontexts/

Working Together

Architect

  • "Align this change with spec and AGENTS precedence."
  • "Propose a migration path with clear review gates."

Prompt Engineer

  • "Keep wrappers thin and move logic into skills."
  • "Preserve quality gates while reducing duplication."

Technical Writer

  • "Rewrite this section for AGENTS-first onboarding."
  • "Make platform-agnostic guidance clearer."

Reviewer

  • "Check for regressions and stale references."
  • "List blocking findings before merge."

Key Components

  • Specification: specs/context_aware_ai_session_spec.md
  • Templates: templates/
  • Skills: skills/
  • Prompt wrappers: prompts/
  • User context samples: usercontexts/

Testing Strategy

  • Validate structural/quality changes using canonical validation skills.
  • Re-run affected validation reports after workflow/guidance changes.
  • Verify references with repository-wide path scans.

Documentation Standards

  • Markdown-first documentation.
  • Relative repository paths for cross-references.
  • No decorative emojis/icons in headings.
  • Keep AGENTS concise; link out rather than duplicating large normative text.

Testing Commands

rg -n "<pattern>" AGENTS.md README.md skills prompts templates specs usercontexts

Future Roadmap

  • Maintain AGENTS-only project-context governance.
  • Continue reducing legacy prompt-era artifacts.
  • Strengthen skill validation and drift-control automation.

Formatting And Path Stability Rules

  • Do not use decorative icons or emojis in headings.
  • Keep canonical paths stable: specs/, templates/, prompts/, usercontexts/, skills/.
  • Use relative repository paths for cross-references.
  • Keep language provider-agnostic.

Update And Drift-Control Rule

When specs/context_aware_ai_session_spec.md changes, audit and update all impacted artifacts:

  • templates/
  • skills/
  • prompts/ wrappers (keep thin; do not duplicate full workflow logic)
  • sample files in usercontexts/
  • README.md
  • AGENTS.md

Key References

  • Specification (v1.5.0): specs/context_aware_ai_session_spec.md
  • Project operational defaults: this root AGENTS.md (Default State For This Repo)
  • User context template: templates/usercontext_template.instructions.md
  • Skill template: templates/skill_template/SKILL.md
  • Create prompts:
    • prompts/skills/create-agents-md.prompt.md
    • prompts/skills/create-usercontext-instructions.prompt.md
    • prompts/skills/create-project-instructions.prompt.md
    • prompts/skills/create-skill.prompt.md
  • Validate prompts:
    • prompts/skills/validate-agents-md.prompt.md
    • prompts/skills/validate-usercontext-instructions.prompt.md
    • prompts/skills/validate-project-instructions.prompt.md
    • prompts/skills/validate-skill.prompt.md
  • Loop prompts:
    • prompts/loop/01-readiness-check.prompt.md
    • prompts/loop/02-implementation.prompt.md
    • prompts/loop/03-self-review.prompt.md
    • prompts/loop/04-learnings.prompt.md (optional)
    • prompts/loop/05-human-in-the-loop.prompt.md
  • Extracted skills index: skills/README.md
  • Sample user context instructions: usercontexts/sample_usercontext.instructions.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free