SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsproject-onboarding

project-onboarding

Coding & development

View repository

Updated 10-15 16:43

About this skill

project-onboarding Protocol

Purpose

Automate skill setup in existing projects through:

  1. Automatic detection of the technology stack
  2. Global discovery of skills with npx skills find
  3. Security audit before installing
  4. Installation and routing to AGENTS.md after human approval (the agent manually updates the routing tables according to each skill's metadata)

General flow

FASE 1: Escaneo y Detección de Stack
    | detecta archivos, dependencias, componentes y scopes
    v
FASE 2: Discovery y Auditoría de Skills
    | busca con npx skills find, deduplica, filtra y rankea
    v
FASE 3: Aprobación e Instalación
    | muestra lista final, espera aprobación explícita e instala
    v
FASE 4: Ruteo
    | el agente actualiza AGENTS.md según metadata scope/auto_invoke
    v
FASE 5: Post-instalación
    | verifica instalación, metadata y AGENTS.md

CRITICAL Rules

  1. ALWAYS use tool question to confirm actions — never assume
  2. DO NOT install without confirmation — always show the list and ask for approval
  3. Detect dynamic scopes — based on the project's actual folders
  4. Route manually — the agent reads metadata.scope + metadata.auto_invoke from each installed skill and updates the tables of the corresponding AGENTS.md files (without external scripts)
  5. Respect the existing structure — do not reorganize the project's folders
  6. Show progress — visual feedback at each phase
  7. DO NOT install during discovery — npx skills find only collects candidates
  8. Block dangerous skills — apply the security policy before showing recommendations
  9. Apply the pattern of find-skills — search, evaluate, present options, and install only after approval

PHASE 1 — Project Scan

Objective: Detect technologies and project structure.

Files to look for

File What it detects
package.json Node.js + dependencies
tsconfig.json TypeScript
pyproject.toml / requirements.txt Python
go.mod Go
Cargo.toml Rust
tailwind.config.* Tailwind CSS
vite.config.* Vite
next.config.* Next.js
nest-cli.json NestJS
docker-compose.yml Docker

Folders to detect (components)

Pattern Component
backend/, api/, server/, apps/backend/, apps/api/ Backend
frontend/, web/, client/, apps/frontend/, apps/web/ Frontend
packages/shared/, shared/, common/ Shared
mcp_server/, mcp/ MCP Server
sdk/, lib/ SDK/Library

Detection script

Run: ./assets/detect-stack.ps1 (Windows) or ./assets/detect-stack.sh (Linux/Mac)

The script generates a JSON with:

{
  "components": {
    "backend": {
      "path": "apps/backend",
      "stack": ["Node.js", "TypeScript", "NestJS", "TypeORM", "MySQL"]
    },
    "frontend": {
      "path": "apps/frontend",
      "stack": ["Node.js", "TypeScript", "React", "Vite", "Tailwind CSS"]
    }
  },
  "tools": ["Docker", "TypeScript"],
  "scopes": ["backend", "frontend"]
}

Presentation to the user

Stack detectado:

Backend (apps/backend):
  ✓ Node.js + TypeScript
  ✓ NestJS
  ✓ TypeORM + MySQL

Frontend (apps/frontend):
  ✓ Node.js + TypeScript
  ✓ React + Vite
  ✓ Tailwind CSS

Herramientas:
  ✓ Docker
  ✓ TypeScript

Scopes detectados: backend, frontend

¿Es correcto? (si/no)

If the user says "no", ask what is missing or wrong and adjust manually.

PHASE 2 — Discovery, Audit, and Recommendation

Objective: Search for relevant skills in the global skills.sh index using npx skills find, not only in known repos.

1. Generate queries from the detected stack

Use the stack from PHASE 1 to create specific queries per component and combined queries.

Example for NestJS + React + Vite + Tailwind + TypeScript + MySQL:

frontend:
  - "react vite tailwind"
  - "react typescript"
  - "vite testing"

backend:
  - "nestjs backend"
  - "typeorm mysql"
  - "typescript testing"

root:
  - "agent workflows"
  - "code review"
  - "software architecture"

See references/stack-mapping.md for query seeds by technology.

2. Run global discovery

Run npx skills find for each query. This searches skills.sh and can return skills from any indexed source, not only from hardcoded repos.

npx skills find "react vite tailwind"
npx skills find "nestjs backend"
npx skills find "typescript testing"

If a query takes too long or fails, retry once with a more specific query. If it fails again, log the timeout and continue with the other queries; do not block the entire onboarding for a single search.

Capture results with this format:

<owner>/<repo>@<skill> <installs> installs

If the output contains ANSI colors, ignore them visually or clean them before parsing.

PowerShell 5.1 can clean ANSI like this:

$raw = npx skills find "nestjs backend"
$clean = [regex]::Replace(($raw -join "`n"), "$([char]27)\[[0-9;]*m", "")
$lines = $clean -split "`r?`n"

for ($i = 0; $i -lt $lines.Count; $i++) {
  if ($lines[$i] -match "^([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)@([A-Za-z0-9_.-]+)\s+([0-9.]+[KkMm]?) installs") {
    $source = $Matches[1]
    $skill = $Matches[2]
    $installs = $Matches[3]
    $url = ""

    if (($i + 1) -lt $lines.Count -and $lines[$i + 1] -match "https://skills\.sh/[^\s]+") {
      $url = $Matches[0]
    }

    "$source@$skill | $installs installs | $url"
  }
}

3. Deduplicate and enrich candidates

For each candidate, store:

{
  "id": "owner/repo@skill-name",
  "source": "owner/repo",
  "skill": "skill-name",
  "installCommand": "npx skills add owner/repo --skill skill-name --agent opencode -y",
  "matchedQuery": "react vite tailwind",
  "component": "frontend",
  "installs": 5000
}

Deduplicate by source + skill. If it appears in several queries, accumulate matchedQueries and raise relevance.

4. Security audit

Before recommending a skill, apply references/security-filter.md.

Classify each candidate as:

Status What it means Action
SAFE The available content was reviewed, there are no dangerous signals, and it has at least one strong trust signal Can be recommended
REVIEW There are doubts about quality, low adoption, or a little-known source Show separately, do not preselect
BLOCKED Contains dangerous patterns or suspicious instructions Do not install

5. Rank

Prioritize by:

  1. Exact match with stack/component
  2. Number of queries where it appeared
  3. Installs
  4. Trustworthy or known source
  5. Absence of risk signals

Do not recommend more than 10 skills per component unless the user asks for it.

Grouping by component

Skills recomendadas para Backend:
  [1] owner/repo@nestjs-best-practices
      Motivo: match NestJS + backend
      Riesgo: SAFE
      Installs: 12K

Skills recomendadas para Frontend:
  [2] secondsky/claude-skills@tailwind-v4-shadcn
      Motivo: match React + Tailwind
      Riesgo: SAFE
      Installs: 5K

Skills para revisar manualmente:
  [3] unknown/repo@react-helper
      Motivo: baja adopción
      Riesgo: REVIEW

Skills bloqueadas:
  [x] random/repo@dangerous-skill
      Motivo: contiene `curl | sh`
      Riesgo: BLOCKED

¿Cuáles instalás?
  - Todas las SAFE
  - Solo backend
  - Solo frontend
  - Selección personalizada (ej: 1,3,5)
  - Ninguna

Confirmation

Use question tool:

question: "¿Qué skills querés instalar?"
options:
  - "Todas las SAFE"
  - "Solo backend"
  - "Solo frontend"
  - "Selección personalizada"
  - "Ninguna"

If the user chooses a skill REVIEW, ask for explicit confirmation mentioning the risk reason. Never install a BLOCKED.

PHASE 3 — Approval and Installation

Objective: Validate that the approved skills are still available and install them only after human approval.

Installation process

For each skill approved by the user:

npx skills add <owner/repo> --skill <skill-name> --agent opencode -y

This downloads the skill to .agents/skills/<skill-name>/.

If the skill belongs to this repository:

npx skills add AgustinAlbonico/ai-customizations --skill <skill-name> --agent opencode -y

Before installing, validate that the source still resolves:

npx skills add <owner/repo> --list

If validation fails, remove that skill from the batch and inform the user before continuing.

Scope assignment

After installing, the agent:

  1. Reads the SKILL.md of each installed skill
  2. Detects which component it belongs to according to the mapping table
  3. Adds metadata if it does not exist:
metadata:
  scope: [backend]  # o frontend, root, etc.
  auto_invoke:
    - "Acción relevante"

Example

# Instalar skill desde un source compatible con npx skills
npx skills add <owner/repo> --skill nestjs-best-practices --agent opencode -y

# Agregar metadata (el agente edita el SKILL.md)
metadata:
  scope: [backend]
  auto_invoke:
    - "Writing NestJS modules"
    - "Creating API endpoints"

PHASE 4 — Routing

Objective: Update AGENTS.md with the installed skills, manually.

How to route (without external scripts)

For each installed skill, the agent:

  1. Reads its SKILL.md and extracts metadata.scope + metadata.auto_invoke. If it has no metadata, it proposes it based on the installed component and adds it.
  2. Resolves the target AGENTS.md according to the scope: root → AGENTS.md root; frontend/backend/shared → the component's AGENTS.md (or the root one if the project has no hierarchy); own scopes → .agents/skill-scopes.json if it exists.
  3. Adds or updates the section ### Auto-invoke Skills with one row per skill: trigger (from auto_invoke) + skill path. Do not duplicate existing rows.

Verification

Show the user:

Skills instaladas y ruteadas:

Backend:
  ✓ nestjs-best-practices → apps/backend/AGENTS.md
  ✓ typescript-advanced-types → apps/backend/AGENTS.md

Frontend:
  ✓ vercel-react-best-practices → apps/frontend/AGENTS.md
  ✓ tailwind-v4-shadcn → apps/frontend/AGENTS.md
  ✓ vite → apps/frontend/AGENTS.md

Transversales:
  ✓ docker-expert → AGENTS.md

AGENTS.md actualizados:
  ✓ AGENTS.md (root)
  ✓ apps/backend/AGENTS.md
  ✓ apps/frontend/AGENTS.md

¿Querés revisar los AGENTS.md generados?

PHASE 5 — Post-installation

Objective: Verify that everything works correctly.

Checklist

  • All skills installed in .agents/skills/
  • Discovery run with npx skills find for component queries
  • Candidates deduplicated and audited before installing
  • User explicitly approved the final list
  • Metadata added to each skill (scope + auto_invoke)
  • AGENTS.md updated with Auto-invoke tables (no duplicates)
  • Dynamic scopes detected correctly

Common problems

Problem Solution
Skill does not appear in AGENTS.md Verify that it has metadata (scope + auto_invoke) and add it manually
Scope not detected Verify that the folder exists and has a manifest (package.json, etc.)
Duplicates in table Clean up duplicate rows in the AGENTS.md

Diagnostic command

# Ver skills instaladas sin metadata scope/auto_invoke
grep -L "scope:" .agents/skills/*/SKILL.md

Use cases

Case 1: New project with a defined stack

Usuario: "hacé onboarding del proyecto"
Agente: escanea → detecta React + NestJS → busca con npx skills find → audita → pide aprobación → instala → rutea

Case 2: Existing project without skills

Usuario: "configurá skills para este proyecto"
Agente: escanea → detecta Django + PostgreSQL → busca skills globales → filtra riesgo → pide aprobación → instala → rutea

Case 3: Add skills to a specific component

Usuario: "instalá skills solo para el frontend"
Agente: detecta frontend → recomienda 4 skills → instala solo esas → rutea

Integration with project-starter

If the user is creating a project from scratch:

  1. Use project-starter to define the stack and bootstrap
  2. After bootstrapping, use project-onboarding to install skills
project-starter → define stack + bootstrap → project-onboarding → instala skills

Resources