manage-skills

Files (2)

• SKILL.md
• agent-install.md

SKILL.md (first lines)

# Manage Skills

This repository is the **single source of truth** for these agent skills. Author
under `skills/`, then distribute via **agent-from-git** (preferred when an agent
can run the install), skills.sh (`npx`), project startup sync, or the optional
Claude Code plugin.

**On invoke for install questions:** read [agent-install.md](agent-install.md) —
zero-deviation agent-from-git procedure; keep `npx` as the supported CLI path.

## Where skills live

| Location | Role |
|----------|------|
| `skills/` in this repo | **Edit here** — git source of truth (Agent Skills layout) |
| `skills/concepts/` | **Uninvokable concepts** (`CONCEPT_*.md`) + disclosed refs (e.g. `PLATFORM-CATALOGS.md`) — synced as sibling `concepts/` |
| `~/.claude/skills/`, `~/.codex/skills/`, `~/.copilot/skills/`, `~/.cursor/skills/` | Global skill folder for that harness only. `sync-local` writes the applied harness, not the others |
| `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.copilot/copilot-instructions.md`, `~/.cursor/rules/marcuskrogh-skills.mdc` | Global instruction file for that harness. Written only when that harness is applied |
| Project `.agents/skills/` | Project skill folder for Cursor, Codex, and Copilot |
| Project `.claude/skills/` | Project skill folder for Claude Code |
| `.claude-plugin/` | Optional Claude Code marketplace manifests |

Ownership and shapes: [writing-for-agents](../writing-for-agents/SKILL.md).
Layout rule: shared composed skills (`jira`, `tracker`, `workflow`) stay
**siblings** of the skills that link to them. Concepts stay at
`../concepts/CONCEPT_*.md` relative to each skill so installs that copy
`concepts/` alongside skill folders keep links intact.

Do not nest shared material under a category folder that skills.sh would flatten away on install — except the dedicated `concepts/` bundle, which sync scripts always copy.

## Install paths

**Agent-from-git (preferred when an agent can install):**

Tell the agent to install from git using the canonical installer — full prompt and
invariants in [agent-install.md](agent-install.md). Mechanical entrypoint:

```bash
curl -fsSL https://raw.githubusercontent.com/marcuskrogh/skills/main/scripts/install-from-git.sh | bash
```

Installs the skill tree for the applied harness only, writes `.skills-version`,
and appends the routing instruction to that harness's instruction file. Cursor
gets `AGENTS.md` and `.cursor/rules/github-skills.mdc`. Claude Code gets
`CLAUDE.md`. Codex gets `AGENTS.md`. Copilot gets
`.github/copilot-instructions.md`. Set `SKILLS_HARNESS` when the running
process is not that harness. Agents must not freestyle an alternate copy layout.

**skills.sh / npx (also supported):**

```bash
npx skills add marcuskrogh/skills
```

Does not wire prefer-workflow pointers — see [agent-install.md](agent-install.md).

**Optional Claude Code plugin:**

```bash
claude plugin marketplace add marcuskrogh/skills
claude plugin install marcus-skills@marcuskrogh
```

**Project startup sync (CI / cloud / VM):**

```powershell
.\scripts\setup-project-sync.ps1 -ProjectPath C:\path\to\repo
```

Add `-WireCursorCloud` only when the project runs on Cursor Cloud and needs
`.cursor/environment.json` (`install` + `start` both run `.agents/sync-skills.sh`
so boots stay on latest `SKILLS_REF` even when a Build snapshot skips install).

## Updating an existing install to latest main

Consuming repos should treat updates as an explicit re-sync to a git ref (usually `main`). Pick the path that matches how skills were installed:

| How skills were installed | Update to latest `main` |
|---------------------------|-------------------------|
| **Agent-from-git** (`install-from-git.sh`) | Re-run the same script (or the agent prompt in [agent-install.md](agent-install.md)), then commit |
| **skills.sh** (project or global) | `npx skills update -y` — or force refresh: `npx skills add marcuskrogh/skills -y` |
| **Startup sync** (`.agents/sync-skills.sh`) | `SKILLS_REF=main bash .agents/sync-skills.sh` (default ref is already `main`) |
| **Copied / committed** via `install-to-project.ps1` | Re-run the install script from an up-to-date clone of this repo, then commit `.agents/skills/` |
| **Claude plugin** | Plugin tracks this repo; update/reinstall the plugin after we ship on `main` |

After agent-from-git, startup sync, or `install-to-project`, check
`.agents/skills/.skills-version` for `repo`, `ref`, and `sha`.

If the project already has an older `.agents/sync-skills.sh`, refresh it from this repo first (re-run `setup-project-sync.ps1` or copy `templates/project-sync/sync-skills.sh`), then sync — older scripts only `git pull` and may not advance cleanly or write a version stamp.

**Pin a version** (agent-from-git or startup sync):

```bash
SKILLS_REF=v1.2.0 bash scripts/install-from-git.sh   # or .agents/sync-skills.sh
SKILLS_REF=<full-sha> bash scripts/install-from-git.sh
SKILLS_REF=main bash scripts/install-from-git.sh       # latest again
```

## After every skill change (authors)

```powershell
cd D:\code\skills
.\scripts\validate-skills.ps1
.\scripts\sync-local.ps1 -Prune
```

`-Prune` removes skill folders from local mirrors that no longer exist in the repo (always keeps `concepts/`).

## First-time setup (this machine)

```powershell
cd D:\code\skills
.\scripts\setup.ps1
```

Validates skills, syncs to local agent homes, installs git hooks so `git pull` re-syncs.

## Writing skills and concepts

From marcuskrogh/skills, MIT.

More from marcuskrogh/skills