# Project Onboarding Adapter

> Adapt this .agents bundle to a frontend project using approved native pointers, local-only overlays, stack detection, skill applicability, tool capabilities, client and verification facts, optional loop memory, and context cache. Do not create app code or overwrite instructions.

- Skill: `ytvee-dev/project-onboarding-adapter` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ytvee-dev/project-onboarding-adapter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ytvee-dev/project-onboarding-adapter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ytvee-dev (https://skillmd.com/u/ytvee-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ytvee-dev/project-onboarding-adapter

---


# Project Onboarding Adapter

## Purpose

Adapt this `.agents` bundle to a host frontend project without creating application source files. For React or Next.js, cache normal target-stack facts. For a non-target frontend project, cache only the detected stack boundary and the framework-agnostic skills that remain usable.

Onboarding must also adapt natively to the installed client target. It creates or refreshes the smallest appropriate host pointer, records client facts in local-only `project/client-profile.md`, and records tool capabilities in local-only `project/mcp-profile.md`.

## Natural Language Trigger Aliases

Route adaptation, initialization, and project-context bootstrap commands to this skill, including `адаптируйся`, `инициализируй .agents`, and `Adapt this .agents bundle to my project.`

## When To Use

- The user asks to adapt this bundle to a new React or Next.js project.
- The user asks to adapt this bundle to a non-target frontend project while keeping applicable design, QA, review, lint, planning, MCP, context, and skill-authoring workflows.
- The user asks to create or refresh the host-root pointer, native client pointer, local project overlays, MCP profile, client profile, design-reference profile, verification facts, loop memory, or path indexes.

## When Not To Use

- Ordinary screenshot-to-code implementation.
- Narrow project overlay refresh after implementation.
- Reusable skill authoring.
- Application scaffolding, package installation, or source file creation.
- Stack-specific React/Next architecture or implementation guidance for a non-target frontend project unless the user explicitly changes the supported stack.

## Required Context

1. Read the host-root native instruction pointer if present and needed for adaptation: `AGENTS.md`, `CLAUDE.md`, or client rules. Inspect only the minimal pointer section.
2. Read bundle-local `AGENTS.md` and `common/core/runtime-core-policy.md`.
3. Read `common/client-adaptation-policy.md` and only the adapter for the resolved canonical target.
4. Read `profiles/react-typescript/PROFILE.md` and its owning policies only when repository evidence confirms the profile.
5. Read `common/skill-applicability-policy.md` when the detected or suspected stack is outside the target stack.
6. Read `common/tool-capability-model.md` and `tool-capabilities-manifest.json` for capability selection.
7. Read `common/context-compaction-rules.md` when loop memory or resumable workflow setup is requested.
8. Read existing `project/**` overlays when present.
9. Inspect only relevant manifests, configs, source entrypoints, routes, styles, assets, and verification scripts.
10. Read `templates/project/client-profile.md` and `templates/project/mcp-profile.md` before creating those local-only profiles.

Read targeted README sections only when they help identify project intent, setup guidance, or documentation drift. Apply `common/readme-policy.md`, and confirm every cached technical fact through manifests, config, source, CI, package scripts, lockfiles, or real results.

## Tool Contract

- Use the `project_files` capability when available. Prefer configured filesystem/project-files MCP for direct project file reads; use host-native file tools when available; use targeted shell reads only as the fallback.
- Use MDN for HTML, CSS, Web APIs, accessibility, and browser behavior when official web platform facts matter.
- Use `context7` only for detected target-stack libraries or tooling when current docs matter.
- Activate `openai_platform_docs` only when current Codex client, plugin, skill, MCP, or configuration behavior affects onboarding.
- Determine Browser or Playwright availability from the current session tool registry or validated `project/mcp-profile.md` facts. Do not invoke either tool during onboarding or MCP detection.
- Do not infer MCP availability from `package.json`, lockfiles, `node_modules`, a running local app, or Playwright dependencies.
- Do not use Figma MCP.
- Missing MCP installation requires explicit user approval after reporting the official source.

## Workflow

1. Classify whether this is Plan Mode or approved execution.
2. Detect the installed target or current client surface. In source, resolve aliases through `bundle-manifest.json`; in a generated target, use its sole shipped adapter.
3. Read that one client adapter and apply its native discovery, pointer, tool, sandbox, and configuration rules. For a generic or unknown client, create no pointer unless the user explicitly requests one.
4. If an expected pointer already exists, do not overwrite it. Propose a merge when existing instructions are non-empty or ambiguous.
5. Detect whether the host project is existing, new/empty, or partially initialized.
6. Detect target-stack fit from manifests, configs, lockfiles, source roots, routes, styles, and entrypoints.
7. If the project fits the target stack, plan or write normal `project/**` overlays for stack, architecture, styling, state, data, verification, design references, MCP profile, client profile, and path indexes.
8. If the user asks for resumable iterative work or loop memory, plan or write local-only `project/loop-memory.md` using `templates/loop-memory.md` as the source pattern.
9. If the project is outside the target stack, continue with limited onboarding: record the stack boundary, skip React/Next path indexes and stack-specific patterns, and write `project/skill-applicability-profile.md` with applicable framework-agnostic skills from `common/skill-applicability-policy.md`.
10. Read `tool-capabilities-manifest.json` for declared capability needs and cache required, available, missing, optional, approved, installed, skipped, or blocked capabilities in `project/mcp-profile.md`.
11. Cache detected client target, native pointer, skill support, and MCP config locations in `project/client-profile.md`.
12. In Plan Mode, return the plan and stop.
13. In approved execution mode, create or update only the approved pointer and local-only overlays, then run available validation checks.

## Output Contract

Final response: return only facts that affect the user's understanding, confidence, or next action. Omit empty fields and workflow narration.

```text
Installed package target or detected client
Native pointer action
Project type and stack facts
Target-stack fit
Applicable framework-agnostic skills when outside target stack
Docs and MCP capability choices
Client profile action
MCP profile action
Overlays to create or update
Loop memory setup
Verification commands
Validation run or blocked
Unknowns
```

## Validation Gates

- `project/**` overlays remain local-only.
- `project/client-profile.md` and `project/mcp-profile.md` are created from templates and marked local-only in copied overlays.
- Native pointers remain small. Claude uses the exact `@.agents/AGENTS.md` import when shared project policy is approved; other pointers reference `.agents/AGENTS.md` instead of mirroring the full policy.
- Existing host instructions are not overwritten without approval.
- README may supply targeted context but never the sole technical fact; README and host docs are not edited during onboarding unless the current user explicitly requests that documentation change.
- Loop memory stores tried, verified, and open facts only in local-only project files.
- Non-target frontend overlays do not claim React/Next implementation support.
- Non-target frontend projects list applicable framework-agnostic skills instead of reporting the whole bundle unusable.
- Capability detection uses `tool-capabilities-manifest.json` and does not depend on Codex-only `agents/openai.yaml` files.
- No application source files are created during onboarding.
- No package, MCP, UI library, styling system, or framework change is made without explicit approval.
- Changed Markdown keeps graph frontmatter and English reusable rules.

## Trigger Evals

Should trigger:

- "адаптируйся"
- "Adapt this .agents bundle to my project."
- "Plan onboarding for this frontend repo."
- "Adapt this bundle to an Astro project but keep only the skills that still apply."
- "Set up local loop memory for this project."
- "Detect whether this install is Codex, Claude, Cursor, or VS Code and create the right pointer."

Should not trigger:

- "Implement this visual spec."
- "Refresh project overlays after this component change."
- "Create a new skill package."
- "Scaffold a new React app."

## Reference Map

- `common/client-adaptation-policy.md`
- `common/codex-official-docs-policy.md`
- `common/tool-capability-model.md`
- `common/mcp-installation-policy.md`
- `common/target-stack-policy.md`
- `common/skill-applicability-policy.md`
- `common/context-compaction-rules.md`
- `common/readme-policy.md`
- `tool-capabilities-manifest.json`
- `templates/project/client-profile.md`
- `templates/project/mcp-profile.md`
- `templates/loop-memory.md`
- `skills/project-context-adapter/SKILL.md`
- `skills/mcp-toolchain-manager/SKILL.md`