Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/marcomc/agents-file-templates-and-skills

Reusable AGENTS.md templates and skills for coding agents
https://github.com/marcomc/agents-file-templates-and-skills

agent-instructions agents-md ai-agent automation cli codex developer-tools markdown python skills templates

Last synced: 26 days ago
JSON representation

Reusable AGENTS.md templates and skills for coding agents

Awesome Lists containing this project

README 

          
# AGENTS File Templates and Skills



Reusable `AGENTS.md` templates and skills for creating, maintaining, and

improving project-specific agent instructions.



## Table of Contents



- [Purpose](#purpose)

- [Repository Layout](#repository-layout)

- [How to Use](#how-to-use)

- [Configuration](#configuration)

- [Skills](#skills)

- [Composable Instructions](#composable-instructions)

- [Auto-Learning Pipeline](#auto-learning-pipeline)

- [Installation Script](#installation-script)

- [Vendor Conventions](#vendor-conventions)

- [Build Workflow](#build-workflow)

- [Template Safety](#template-safety)

- [Development](#development)



## Purpose



This repository keeps reusable agent-instruction templates for developers who

want consistent agent behavior without copying the same rules into every

project by hand. It is built around one canonical global policy in

`${HOME}/AGENTS.md` plus smaller project-type overlays that can be merged into

each repository.



The repository supports two recurring workflows:



1. **Initialize or refresh a project's agent instructions from curated templates.**

  This gives new projects a useful baseline quickly: global policy reference,

  detected project-type guidance, validation rules, and a preserved local

  section for project-specific rules.



2. **Mine existing project instruction files and promote reusable lessons back into

  the template library.** This keeps templates improving as your real project

  rules evolve instead of letting good instructions stay trapped in one repo.



The standard output is `AGENTS.md`, which is the portable default used by this

repository. When needed, the same templates can generate agent-specific files

such as `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`.



## Repository Layout



```text

.

├── README.md

├── TODO.md

├── templates.yml

├── Makefile

├── docs/

│   └── composable-agent-instructions.md

├── scripts/

│   ├── install_agent_template_skills.sh

│   └── privacy_scan.py

├── skills/

│   ├── init-agents-file/

│   └── update-agents-file-templates/

└── templates/

    ├── global/

    │   └── AGENTS.md

    └── project-types/

        ├── ansible/

        ├── bash/

        ├── cli/

        ├── docker/

        ├── docs/

        ├── generic-development/

        ├── github-release/

        ├── hardware-device/

        ├── home-assistant/

        ├── macos/

        ├── python/

        ├── raspberry-pi/

        ├── web/

        └── workspace/

```



Temporary mining outputs belong under `.work/`. That directory is ignored and

must not be committed.



## How to Use



Clone the repository, then install the skills into the agents you use:



```bash

git clone  agents-file-templates-and-skills

cd agents-file-templates-and-skills

make install AGENTS="openai claude opencode"

```



By default, the installer copies every `skills//SKILL.md` skill into

`${HOME}/.agents/skills`, then creates agent-specific symlinks back to that

canonical location. Add `--mode symlink` if you want the canonical

`${HOME}/.agents/skills/` entries to point back to this repository

instead:



```bash

make install-symlink AGENTS="codex claude"

```



Remove installed skills with:



```bash

make uninstall AGENTS="openai claude"

```



After installation, the normal workflow is to ask your coding agent to use the

skill from inside a project. For example:



```text

Use init-agents-file to initialize this project's agent instructions.

```



The skill should inspect the current project, locate the template repository

from its installed configuration, generate a dry run, and apply only after the

target file and content are clear. By default it writes the portable standard

`AGENTS.md`. If you want an agent-specific file, ask for that explicitly, for

example `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`.



The Python scripts under `skills/*/scripts/` are implementation helpers and

manual fallback entrypoints. They are not the preferred daily interface.



To create a global policy for a new user, start from

`templates/global/AGENTS.md`, replace placeholders, and place the result at

`${HOME}/AGENTS.md`.



## Configuration



`templates.yml` is the manifest for template selection, detection, merge order,

and placeholders.



Important fields:



- `placeholders`: values expected by templates.

- `project_types`: curated overlays and detection hints.

- `scan_defaults`: conservative defaults for mining existing projects.

- `privacy`: patterns and review rules used before template promotion.



The skills must not assume a fixed filesystem layout. Users can configure scan

roots and depth for their own machines. If a request is ambiguous, the agent

should inspect the current project, infer a likely scope, and ask before a broad

scan.



## Skills



The portable skill contract is `SKILL.md` plus optional bundled resources such

as `scripts/`, `references/`, and `assets/`. The files named

`agents/openai.yaml` are only OpenAI/Codex user-interface metadata. They help

Codex display friendly skill names and suggested prompts, but they are not the

skill logic and other agents can ignore them.



There are no equivalent adapter files for Claude Code, GitHub Copilot, Gemini,

or OpenCode because their current conventions use Markdown instruction files,

settings, or their own agent config formats rather than a shared metadata file.

This repository keeps `SKILL.md` as canonical and adds product-specific adapters

only when a product has a real adapter convention.



### `init-agents-file`



Use this skill to create or refresh a project instruction file. It detects

project types, merges matching overlays, replaces placeholders, and preserves a

local editable section. It can generate standard `AGENTS.md` or agent-specific

files such as `CLAUDE.md`, `GEMINI.md`, or

`.github/copilot-instructions.md`.



### `update-agents-file-templates`



Use this skill to update curated templates over time. It supports:



- Full mining from configured project roots.

- Single-template mining, such as updating only the Python template.

- Current-project promotion, where reusable rules from the current project are

  proposed for one or more templates.

- Learning-upstream summaries for ignored drafts created by

  `agent-learning-system`.

- Explicit reviewed apply for approved learning-upstream drafts.

- Out-of-sync reports for generated project `AGENTS.md` files.



Mining creates ignored working artifacts. Curated templates are updated only

after review and privacy scrubbing.



## Composable Instructions



Reusable instruction composition is documented in

[`docs/composable-agent-instructions.md`](docs/composable-agent-instructions.md).

This model treats the global policy as a director file, project-type overlays as

composable atoms, and project `AGENTS.md` files as generated compositions with a

preserved local section.



## Auto-Learning Pipeline



This repository is the template side of the two-repository auto-learning

pipeline. The orchestration runbook lives in

`${HOME}/Development/agent-learning-system/docs/auto-learning-pipeline-automations.md`.



The required weekly template automation runs in this repository and must:



| Step | Requirement |

| --- | --- |

| Summarize | Inspect `.work/learning-upstream/` handoffs |

| Gate | Apply only `Review status: approved` plus `Privacy verdict: clean` |

| Validate | Run Markdown, Python, unit-test, and privacy checks |

| Report | Write `.work/out-of-sync/` refresh reports |

| Avoid | No stage, commit, push, pull request, or unrelated edits |



Use

[`docs/composable-agent-instructions.md#automation-integration`](docs/composable-agent-instructions.md#automation-integration)

for the template-side command contract.



## Installation Script



Skill installation is intentionally not a skill: it must work before any agent

has loaded this repository's skills. Use `make install` or the underlying shell

script:



```bash

scripts/install_agent_template_skills.sh --agent codex --agent claude --apply

```



If no `--agent` is provided and the script is attached to a terminal, it asks

which agents to install for. In non-interactive mode it defaults to OpenAI/Codex.



The installer writes a local `config/template_repo_path.txt` into installed

copied canonical skills so they can find this template repository later without

users exporting environment variables. Symlink installs do not need that config.



Selected agents receive symlinks from their native skill directories to

`${HOME}/.agents/skills/`. The supported fanout targets are Codex,

Claude Code, OpenCode, GitHub Copilot, Gemini CLI, and OpenClaw.



## Vendor Conventions



| Tool / company | Main project instruction file | Global/user instruction file | Skills format | Metadata adapter |

| --- | --- | --- | --- | --- |

| OpenAI Codex | `AGENTS.md` convention, plus Codex skills | Codex-local skills directories | Agent Skills: `SKILL.md` plus optional `scripts/`, `references/`, `assets/` | Optional `agents/openai.yaml`, OpenAI/Codex UI metadata |

| Anthropic Claude Code | `CLAUDE.md` or `.claude/CLAUDE.md` | `~/.claude/CLAUDE.md`; local `CLAUDE.local.md` | Agent Skills in `~/.claude/skills/` or project `.claude/skills/` | No separate adapter required; metadata is in `SKILL.md` frontmatter |

| GitHub Copilot | `.github/copilot-instructions.md`; path-specific `.github/instructions/*.instructions.md`; partial support for `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` varies by feature | Personal and organization instructions in GitHub/Copilot settings | Agent Skills in `${HOME}/.copilot/skills/` when enabled; prompt files `*.prompt.md`; repository instructions are Markdown files | No metadata adapter; mostly Markdown files and GitHub settings |

| Google Gemini CLI | `GEMINI.md` by default | `~/.gemini/GEMINI.md` | Context files and CLI skills, depending on local version and configuration | No vendor adapter for instruction files; configurable context filenames |

| OpenCode | `AGENTS.md` | `~/.config/opencode/AGENTS.md` | Claude-compatible skills and custom agents | Uses `opencode.json` or Markdown frontmatter for custom agents, not an `openai.yaml` equivalent |

| OpenClaw | Tool-specific project instructions | Detected local config root, preferring `${HOME}/.openclaw`, `${HOME}/.clawdbot`, then `${HOME}/.moltbot` | Agent Skills under the detected `skills/` directory | No separate adapter required |



The practical rule for this repository is: keep curated templates in

`templates/**/AGENTS.md`, then generate the output filename each target agent

expects.



## Build Workflow



This repository was designed with a multi-agent workflow:



1. Scaffold the repository, manifest, templates, skills, and ignored working

   directories.

2. Scan existing project `AGENTS.md` files into a matrix of project types,

   evidence, reusable instruction categories, and privacy risk notes.

3. Distill category-specific drafts from the matrix and existing project rules.

4. Curate public-safe templates from the drafts.

5. Implement and install the skills.

6. Validate Markdown, scripts, privacy checks, and generated output.



If the process changes during future updates, refresh this section so the

repository remains reproducible.



## Template Safety



Curated templates must be reusable by other people. Do not commit:



- Personal home paths.

- Email addresses.

- Private domains or hostnames.

- Secrets, tokens, passwords, cookies, or account identifiers.

- Local device names, IP addresses, or private network details.



Use placeholders such as `${HOME}`, `${USER_NAME}`, `${PRIMARY_DOMAIN}`,

`${OBSIDIAN_VAULT_PATH}`, and `${PROJECT_NAME}` instead.



## Development



Validate changes before committing:



```bash

markdownlint --config ~/.markdownlint.json README.md TODO.md docs/*.md templates/**/*.md skills/**/*.md

python3 scripts/privacy_scan.py .

python3 skills/init-agents-file/scripts/init_agents_file.py --project .

python3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --scan-root . --max-depth 2

python3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --learning-upstream-summary

python3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --scan-root . --out-of-sync-report

python3 -m unittest discover -s tests

shellcheck --enable=all scripts/install_agent_template_skills.sh

scripts/install_agent_template_skills.sh --agent openai

```