{"id":51224937,"url":"https://github.com/marcomc/agents-file-templates-and-skills","last_synced_at":"2026-06-28T10:30:23.328Z","repository":{"id":362924778,"uuid":"1235514556","full_name":"marcomc/agents-file-templates-and-skills","owner":"marcomc","description":"Reusable AGENTS.md templates and skills for coding agents","archived":false,"fork":false,"pushed_at":"2026-06-13T20:55:46.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T10:30:22.870Z","etag":null,"topics":["agent-instructions","agents-md","ai-agent","automation","cli","codex","developer-tools","markdown","python","skills","templates"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcomc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-11T11:55:25.000Z","updated_at":"2026-06-13T20:53:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcomc/agents-file-templates-and-skills","commit_stats":null,"previous_names":["marcomc/agents-file-templates-and-skills"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/marcomc/agents-file-templates-and-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagents-file-templates-and-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagents-file-templates-and-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagents-file-templates-and-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagents-file-templates-and-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcomc","download_url":"https://codeload.github.com/marcomc/agents-file-templates-and-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fagents-file-templates-and-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34885801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-instructions","agents-md","ai-agent","automation","cli","codex","developer-tools","markdown","python","skills","templates"],"created_at":"2026-06-28T10:30:20.571Z","updated_at":"2026-06-28T10:30:23.320Z","avatar_url":"https://github.com/marcomc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AGENTS File Templates and Skills\n\nReusable `AGENTS.md` templates and skills for creating, maintaining, and\nimproving project-specific agent instructions.\n\n## Table of Contents\n\n- [Purpose](#purpose)\n- [Repository Layout](#repository-layout)\n- [How to Use](#how-to-use)\n- [Configuration](#configuration)\n- [Skills](#skills)\n- [Composable Instructions](#composable-instructions)\n- [Auto-Learning Pipeline](#auto-learning-pipeline)\n- [Installation Script](#installation-script)\n- [Vendor Conventions](#vendor-conventions)\n- [Build Workflow](#build-workflow)\n- [Template Safety](#template-safety)\n- [Development](#development)\n\n## Purpose\n\nThis repository keeps reusable agent-instruction templates for developers who\nwant consistent agent behavior without copying the same rules into every\nproject by hand. It is built around one canonical global policy in\n`${HOME}/AGENTS.md` plus smaller project-type overlays that can be merged into\neach repository.\n\nThe repository supports two recurring workflows:\n\n1. **Initialize or refresh a project's agent instructions from curated templates.**\n  This gives new projects a useful baseline quickly: global policy reference,\n  detected project-type guidance, validation rules, and a preserved local\n  section for project-specific rules.\n\n2. **Mine existing project instruction files and promote reusable lessons back into\n  the template library.** This keeps templates improving as your real project\n  rules evolve instead of letting good instructions stay trapped in one repo.\n\nThe standard output is `AGENTS.md`, which is the portable default used by this\nrepository. When needed, the same templates can generate agent-specific files\nsuch as `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`.\n\n## Repository Layout\n\n```text\n.\n├── README.md\n├── TODO.md\n├── templates.yml\n├── Makefile\n├── docs/\n│   └── composable-agent-instructions.md\n├── scripts/\n│   ├── install_agent_template_skills.sh\n│   └── privacy_scan.py\n├── skills/\n│   ├── init-agents-file/\n│   └── update-agents-file-templates/\n└── templates/\n    ├── global/\n    │   └── AGENTS.md\n    └── project-types/\n        ├── ansible/\n        ├── bash/\n        ├── cli/\n        ├── docker/\n        ├── docs/\n        ├── generic-development/\n        ├── github-release/\n        ├── hardware-device/\n        ├── home-assistant/\n        ├── macos/\n        ├── python/\n        ├── raspberry-pi/\n        ├── web/\n        └── workspace/\n```\n\nTemporary mining outputs belong under `.work/`. That directory is ignored and\nmust not be committed.\n\n## How to Use\n\nClone the repository, then install the skills into the agents you use:\n\n```bash\ngit clone \u003cREPOSITORY_URL\u003e agents-file-templates-and-skills\ncd agents-file-templates-and-skills\nmake install AGENTS=\"openai claude opencode\"\n```\n\nBy default, the installer copies every `skills/\u003cname\u003e/SKILL.md` skill into\n`${HOME}/.agents/skills`, then creates agent-specific symlinks back to that\ncanonical location. Add `--mode symlink` if you want the canonical\n`${HOME}/.agents/skills/\u003cname\u003e` entries to point back to this repository\ninstead:\n\n```bash\nmake install-symlink AGENTS=\"codex claude\"\n```\n\nRemove installed skills with:\n\n```bash\nmake uninstall AGENTS=\"openai claude\"\n```\n\nAfter installation, the normal workflow is to ask your coding agent to use the\nskill from inside a project. For example:\n\n```text\nUse init-agents-file to initialize this project's agent instructions.\n```\n\nThe skill should inspect the current project, locate the template repository\nfrom its installed configuration, generate a dry run, and apply only after the\ntarget file and content are clear. By default it writes the portable standard\n`AGENTS.md`. If you want an agent-specific file, ask for that explicitly, for\nexample `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`.\n\nThe Python scripts under `skills/*/scripts/` are implementation helpers and\nmanual fallback entrypoints. They are not the preferred daily interface.\n\nTo create a global policy for a new user, start from\n`templates/global/AGENTS.md`, replace placeholders, and place the result at\n`${HOME}/AGENTS.md`.\n\n## Configuration\n\n`templates.yml` is the manifest for template selection, detection, merge order,\nand placeholders.\n\nImportant fields:\n\n- `placeholders`: values expected by templates.\n- `project_types`: curated overlays and detection hints.\n- `scan_defaults`: conservative defaults for mining existing projects.\n- `privacy`: patterns and review rules used before template promotion.\n\nThe skills must not assume a fixed filesystem layout. Users can configure scan\nroots and depth for their own machines. If a request is ambiguous, the agent\nshould inspect the current project, infer a likely scope, and ask before a broad\nscan.\n\n## Skills\n\nThe portable skill contract is `SKILL.md` plus optional bundled resources such\nas `scripts/`, `references/`, and `assets/`. The files named\n`agents/openai.yaml` are only OpenAI/Codex user-interface metadata. They help\nCodex display friendly skill names and suggested prompts, but they are not the\nskill logic and other agents can ignore them.\n\nThere are no equivalent adapter files for Claude Code, GitHub Copilot, Gemini,\nor OpenCode because their current conventions use Markdown instruction files,\nsettings, or their own agent config formats rather than a shared metadata file.\nThis repository keeps `SKILL.md` as canonical and adds product-specific adapters\nonly when a product has a real adapter convention.\n\n### `init-agents-file`\n\nUse this skill to create or refresh a project instruction file. It detects\nproject types, merges matching overlays, replaces placeholders, and preserves a\nlocal editable section. It can generate standard `AGENTS.md` or agent-specific\nfiles such as `CLAUDE.md`, `GEMINI.md`, or\n`.github/copilot-instructions.md`.\n\n### `update-agents-file-templates`\n\nUse this skill to update curated templates over time. It supports:\n\n- Full mining from configured project roots.\n- Single-template mining, such as updating only the Python template.\n- Current-project promotion, where reusable rules from the current project are\n  proposed for one or more templates.\n- Learning-upstream summaries for ignored drafts created by\n  `agent-learning-system`.\n- Explicit reviewed apply for approved learning-upstream drafts.\n- Out-of-sync reports for generated project `AGENTS.md` files.\n\nMining creates ignored working artifacts. Curated templates are updated only\nafter review and privacy scrubbing.\n\n## Composable Instructions\n\nReusable instruction composition is documented in\n[`docs/composable-agent-instructions.md`](docs/composable-agent-instructions.md).\nThis model treats the global policy as a director file, project-type overlays as\ncomposable atoms, and project `AGENTS.md` files as generated compositions with a\npreserved local section.\n\n## Auto-Learning Pipeline\n\nThis repository is the template side of the two-repository auto-learning\npipeline. The orchestration runbook lives in\n`${HOME}/Development/agent-learning-system/docs/auto-learning-pipeline-automations.md`.\n\nThe required weekly template automation runs in this repository and must:\n\n| Step | Requirement |\n| --- | --- |\n| Summarize | Inspect `.work/learning-upstream/` handoffs |\n| Gate | Apply only `Review status: approved` plus `Privacy verdict: clean` |\n| Validate | Run Markdown, Python, unit-test, and privacy checks |\n| Report | Write `.work/out-of-sync/` refresh reports |\n| Avoid | No stage, commit, push, pull request, or unrelated edits |\n\nUse\n[`docs/composable-agent-instructions.md#automation-integration`](docs/composable-agent-instructions.md#automation-integration)\nfor the template-side command contract.\n\n## Installation Script\n\nSkill installation is intentionally not a skill: it must work before any agent\nhas loaded this repository's skills. Use `make install` or the underlying shell\nscript:\n\n```bash\nscripts/install_agent_template_skills.sh --agent codex --agent claude --apply\n```\n\nIf no `--agent` is provided and the script is attached to a terminal, it asks\nwhich agents to install for. In non-interactive mode it defaults to OpenAI/Codex.\n\nThe installer writes a local `config/template_repo_path.txt` into installed\ncopied canonical skills so they can find this template repository later without\nusers exporting environment variables. Symlink installs do not need that config.\n\nSelected agents receive symlinks from their native skill directories to\n`${HOME}/.agents/skills/\u003cname\u003e`. The supported fanout targets are Codex,\nClaude Code, OpenCode, GitHub Copilot, Gemini CLI, and OpenClaw.\n\n## Vendor Conventions\n\n| Tool / company | Main project instruction file | Global/user instruction file | Skills format | Metadata adapter |\n| --- | --- | --- | --- | --- |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n\nThe practical rule for this repository is: keep curated templates in\n`templates/**/AGENTS.md`, then generate the output filename each target agent\nexpects.\n\n## Build Workflow\n\nThis repository was designed with a multi-agent workflow:\n\n1. Scaffold the repository, manifest, templates, skills, and ignored working\n   directories.\n2. Scan existing project `AGENTS.md` files into a matrix of project types,\n   evidence, reusable instruction categories, and privacy risk notes.\n3. Distill category-specific drafts from the matrix and existing project rules.\n4. Curate public-safe templates from the drafts.\n5. Implement and install the skills.\n6. Validate Markdown, scripts, privacy checks, and generated output.\n\nIf the process changes during future updates, refresh this section so the\nrepository remains reproducible.\n\n## Template Safety\n\nCurated templates must be reusable by other people. Do not commit:\n\n- Personal home paths.\n- Email addresses.\n- Private domains or hostnames.\n- Secrets, tokens, passwords, cookies, or account identifiers.\n- Local device names, IP addresses, or private network details.\n\nUse placeholders such as `${HOME}`, `${USER_NAME}`, `${PRIMARY_DOMAIN}`,\n`${OBSIDIAN_VAULT_PATH}`, and `${PROJECT_NAME}` instead.\n\n## Development\n\nValidate changes before committing:\n\n```bash\nmarkdownlint --config ~/.markdownlint.json README.md TODO.md docs/*.md templates/**/*.md skills/**/*.md\npython3 scripts/privacy_scan.py .\npython3 skills/init-agents-file/scripts/init_agents_file.py --project .\npython3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --scan-root . --max-depth 2\npython3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --learning-upstream-summary\npython3 skills/update-agents-file-templates/scripts/update_agents_templates.py --template-repo . --scan-root . --out-of-sync-report\npython3 -m unittest discover -s tests\nshellcheck --enable=all scripts/install_agent_template_skills.sh\nscripts/install_agent_template_skills.sh --agent openai\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fagents-file-templates-and-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcomc%2Fagents-file-templates-and-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fagents-file-templates-and-skills/lists"}