home / skills / gpolanco / skills-as-context / skill-integrator

skill-integrator skill

safe

/skills/skill-integrator

This skill activates already-downloaded AI agent skills in external projects by updating AGENTS.md and skills/README.md according to the canonical templates.

npx playbooks add skill gpolanco/skills-as-context --skill skill-integrator

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.0 KB

---

name: skill-integrator
description: Orchestrate and activate local AI Agent Skills in external projects (consumer repos) by updating AGENTS.md and the local skills catalog.
license: Apache-2.0
metadata:
author: gpolanco
version: "1.1.1"
scope: [root]
auto_invoke: "Help me integrate skills"
allowed-tools: [Read, Write, Bash]
----------------------------------

# Skill Integrator ⚙️

## TL;DR (REQUIRED)

* This skill is used **ONLY in external projects (consumer repos)**.
* Your job is to **activate already-downloaded skills** by updating **only**:

  * `AGENTS.md`
  * `skills/README.md`
* **DO NOT** modify any `SKILL.md` content.
* **MUST** follow the exact orchestration process defined in:

  * `reference/workflow.md`

---

## 🚨 CRITICAL: Reference Workflow is Mandatory

This `SKILL.md` defines the contract and limits of the integrator.

For **exact steps, ordering, and guardrails**, you **MUST** read and follow:

* `reference/workflow.md`

If the workflow is not followed exactly, **stop and ask for clarification**.

---

## When to use

Use this skill **in external projects (consumer repos)** when the user asks to:

* integrate or activate skills in a repository
* set up or regenerate `AGENTS.md`
* generate or sync `skills/README.md` as a catalog view
* adopt skills after a stack change (e.g. added `zod`, `supabase`, `tailwind`)

Do **NOT** use this skill to maintain or modify the **skills-as-context** repository itself.

---

## Outputs (what you are allowed to change)

### ✅ Allowed modifications

* `AGENTS.md`
* `skills/README.md`

### ❌ Not allowed

* Any file under `skills/**/SKILL.md`
* Any project source code or configuration files

---

## Core principles

### ALWAYS

* **Discover first**: inspect `package.json`, project `README.md`, and the directory structure.
* **Select minimal, relevant skills**: only those that match the detected stack.
* **Preserve project intent**: do not overwrite existing custom rules without surfacing them.
* **Use canonical templates** (fetched as raw content):

  * `templates/AGENTS.template.md`
  * `templates/SKILLS_README.template.md`
* **Copy templates exactly**: fill placeholders only, keep headings and table structures intact.

### NEVER

* Activate skills that clearly do not apply to the project.
* Modify the content of individual `SKILL.md` files.
* Invent new sections or rules outside the provided templates.

---

## Integration flow (high level)

This skill orchestrates the integration but does **not** define the procedure inline.

High-level phases:

1. **Discovery** — detect stack, architecture, and skills directory.
2. **Selection** — propose the minimal set of relevant skills.
3. **Confirmation** — ask the user before writing any files.
4. **Orchestration** — update `AGENTS.md` and `skills/README.md` using canonical templates.
5. **Verification** — ensure paths, references, and catalogs are correct.

> For the exact implementation steps, edge cases, and commands, always defer to `reference/workflow.md`.

Overview

This skill orchestrates activation of local AI agent skills inside external projects by updating AGENTS.md and the project's skills catalog file. It selects minimal, relevant skills based on the detected stack and writes canonical templates into the allowed files. The integrator enforces a mandatory reference workflow and halts if the workflow is unclear.

How this skill works

It first discovers project metadata and the skills directory by inspecting package manifests, the root README, and directory structure. It then selects a minimal set of matching skills, asks for user confirmation, and updates AGENTS.md and the skills catalog file using canonical templates. After writing, it verifies paths and references and reports what changed. If any step deviates from the prescribed reference workflow, the process stops and requests clarification.

When to use it

When activating already-downloaded skills in an external project
When generating or regenerating AGENTS.md for a consumer repo
When creating or syncing the skills catalog view for a project
After a stack change that may require different skills (new DB, UI, or validation libs)
When you need a minimal, opinionated set of skills matched to the detected stack

Best practices

Always run the discovery phase first: inspect package manifests and top-level docs before selecting skills
Select only the minimal skills that clearly map to the detected stack and architecture
Do not alter individual skill content; only update the allowed files using canonical templates
Ask for user confirmation before writing files and list the exact changes to be made
Follow the reference workflow exactly; if any ambiguity arises, stop and request clarification

Example use cases

Onboard agent skills into a freshly cloned consumer repo and produce AGENTS.md
Regenerate the project skills catalog after adding a new service or library
Enable only database- or UI-related skills when a repo adds supabase or tailwind
Sync catalog and agent manifests after a change in project structure
Provide a minimal curated skills set for CI checks that rely on documented agents

FAQ

What if the reference workflow is not available or ambiguous?

Stop and ask for clarification. Do not proceed until the exact workflow steps and ordering are provided.

Can I activate skills that do not match the project stack?

No. Never activate skills that clearly do not apply. Only propose minimal, relevant skills detected during discovery.