# Project integration

Documentation checked September 6, 2026. Each skill follows the [Agent Skills format](https://agentskills.io/specification): a named folder containing `SKILL.md` and any linked resources. The installed source is ordinary project files; no global settings, hooks or symlinks are required.

## One shared library

The default installation places the guide at `.agents/SKILLS.md` and skill bodies at `.agents/skills/<discipline>/<skill-name>/SKILL.md`. Examples and data sit beside `skills/` so relative links keep working.

| Tool or convention | Project entrypoint | How it uses the skills |
| --- | --- | --- |
| Codex | `AGENTS.md` | Recursive native discovery under `.agents/skills/`, plus the guide |
| Cursor | Shared `.agents/skills/`; optional `.cursor/rules/project-skills.mdc` | Recursive native discovery, plus a rule when configured |
| Claude Code | `CLAUDE.md` | Reads the guide and selected canonical files; no duplicate Claude skill wrappers |
| Gemini CLI | `GEMINI.md` | Project guide adapter |
| GitHub Copilot | `.github/copilot-instructions.md` | Project guide adapter |
| Windsurf / Devin Desktop | `.windsurf/rules/project-skills.md` | Project guide adapter using the documented legacy fallback |
| Project design notes | `DESIGN.md` | Optional manual convention |

Browser setup adds the Codex and Claude project entrypoints by default and adds other minimal adapters for detected tool configurations. Manual adapter files are provided for explicit setup. `AGENTS.md` and `CLAUDE.md` are uppercase, case-sensitive names.

Native discovery can expose all installed skill names and descriptions to the host. The guide asks the agent to read only the skill bodies and resources needed for the current task; it does not hide the rest of the native metadata. Claude's guide route does not claim that the skills appear in its native selector. Refresh or restart a tool if newly installed files are not recognized.

Model behavior, permissions, host versions and configuration affect use. Verify that the project guide is available, then complete a small task. If automatic discovery fails, explicitly ask the agent to read `.agents/SKILLS.md`. File placement checks do not certify every host or guarantee its behavior.

Devin Desktop prefers `.devin/rules`; its documentation retains `.windsurf/rules` as a supported legacy fallback. The supplied adapter uses that fallback with `trigger: always_on`. `DESIGN.md` records project decisions but is not universally discovered. Vendor names do not imply endorsement.

## Local installation

Browser installation uses the File System Access API: a supported browser, a secure context, a user-initiated folder choice and write permission are required. Chrome, Edge and Dia are the intended browser route; do not assume Safari or Firefox support. Browser and operating-system permission prompts vary. The Python 3.10+ command-line fallback is documented in [START-HERE.md](START-HERE.md).

Both routes keep the installed source project-local and preserve conflicts. `.agents/skill-install.json` records installed files and stores original adapter bytes for restoration. Keep it until you no longer need the managed installation. Older installations under `.rival/workshop` must be uninstalled or deliberately migrated first; edited legacy files are protected.

## Primary references

- [Agent Skills specification](https://agentskills.io/specification).
- [Codex skills](https://learn.chatgpt.com/docs/build-skills) and [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
- [Codex recursive loader source](https://github.com/openai/codex/blob/ad931a45b201e3877d6ba542ba5dbbd85e7e31b4/codex-rs/ext/skills/src/loader/host.rs), pinned to the inspected revision.
- [Claude Code skills](https://code.claude.com/docs/en/skills).
- [Cursor skills](https://prod.cursor.com/docs/skills) and [project rules](https://prod.cursor.com/help/customization/rules).
- [Gemini CLI context](https://geminicli.com/docs/cli/gemini-md/).
- [Copilot repository instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions-in-your-ide/add-repository-instructions-in-your-ide).
- [Windsurf / Devin Desktop rules](https://docs.devin.ai/desktop/cascade/memories).
- [MDN directory picker](https://developer.mozilla.org/en-US/docs/Web/API/Window/showDirectoryPicker).