--- name: skill-manager description: > Create, structure, refine, and deploy Agent Skills following the agentskills.io specification. Use this skill when asked to build a new skill, create a SKILL.md file, package agent instructions into a reusable skill, or improve an existing skill's description, structure, or content. Also use when someone wants to turn a workflow, procedure, or set of instructions into a portable skill that works across Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agents — or wants to deploy, install, publish, or symlink any skill into the agent skill directories ($HOME/.agents/skills, $HOME/.claude/skills), even if they just say "make this skill available". license: Proprietary metadata: author: workspace-swiss-knife version: "1.0" spec: agentskills.io/specification origin-repository: git@github.ibm.com:CTOTools-skills-code-agent/skill-manager.git origin-path: $HOME/projects-ibm/cognitive-architect/workspace-skills-code-agent/skill-manager compatibility: Designed for Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments --- # Skill Manager Build, manage, and deploy well-formed [Agent Skills](https://agentskills.io/specification) — the portable, open format for packaging reusable agent instructions. ## Skill structure Every skill is a directory. The only required file is `SKILL.md`: ``` .agents/skills// ├── SKILL.md # Required: YAML frontmatter + instructions ├── references/ # Optional: detailed reference docs loaded on demand ├── assets/ # Optional: templates, schemas, data files └── scripts/ # Optional: executable scripts the agent can run ├── Taskfile.yml # Required — pure aggregator: only includes: + default task ├── package.json # Required when TypeScript/JS code is present ├── tsconfig.json # Required when TypeScript code is present ├── .gitignore # Required when scripts/ exists ├── .scripts/ # Shell modules (Taskfile → api → lib), one folder per module │ └── / # e.g. diagram/, validator/, scaffolder/ │ ├── Taskfile.yml │ ├── api/ # Thin wrappers — source lib/--index.sh, call one function │ └── lib/ # --index.sh, --index-api.sh, --env-vars-*.sh, -.sh └── src/ # All non-shell source: TypeScript, Python, JS, etc. # ❌ NO source files (.py/.ts/.js/.sh) directly in scripts/ root # ❌ Root Taskfile.yml must NOT have inline cmds — it only includes: module Taskfiles ``` **Root `scripts/Taskfile.yml` pattern — aggregator only:** ```yaml version: "3" includes: diagram: ./.scripts/diagram/Taskfile.yml # add more modules here tasks: default: cmds: - task --list-all silent: true ``` The root Taskfile **never** contains inline `python ...` or `bash ...` commands. All logic lives inside module Taskfiles under `.scripts/`. Tasks in the root Taskfile may delegate to a module task via `task: module:action` but must not contain logic themselves. Default location for skills: `.agents/skills//` ## Available scripts This skill ships a `skill-tools` TypeScript CLI under `scripts/`. All commands run via `task` from the `scripts/` directory: ```bash cd .agents/skills/skill-manager/scripts # Validate any skill directory (TypeScript CLI via cli module) task validate -- --skill-dir="/absolute/path/to/skill" # or directly via cli module: task cli:validate -- --skill-dir="/absolute/path/to/skill" # Scaffold a new skill from the built-in template task scaffold -- --skill-name="my-skill" --output-dir="/path/to/.agents/skills" # or directly via cli module: task cli:scaffold -- --skill-name="my-skill" --output-dir="/path/to/.agents/skills" # Deploy a skill into $HOME/.agents/skills and $HOME/.claude/skills task deploy -- --skill-dir="/absolute/path/to/skill" # copy instead of symlink, replace existing real directories: task deploy -- --skill-dir="/absolute/path/to/skill" --mode=copy --force # Build TypeScript to dist/ task build # or directly via cli module: task cli:build # Shell-only validation (no Node.js required) task validator:execute -- --skill-dir="/absolute/path/to/skill" # Show environment vars (base module) task base:environment:show ``` TypeScript CLI actions (run via `cli` module → `src/`): - **`validate`** (`src/actions/validate/action.ts`) — 13-check validation against agentskills.io spec; YAML output with per-check detail - **`scaffold`** (`src/actions/scaffold/action.ts`) — creates `/SKILL.md` + `references/` + `assets/`; outputs YAML with created paths and next-steps - **`deploy`** (`src/actions/deploy/action.ts`) — deploys any skill into the agent skill directories; outputs YAML with per-target status Shell modules under `scripts/.scripts/`: - **`loggers/`** — logging utilities (`_loggers_info`, `_loggers_debug`, `_loggers_warn`, `_loggers_error`, `_loggers_trace`) - **`base/`** — base utilities (`_base_ensureEnvironmentVariable`, `_base_environment_show`, `_base_mask`); exposes `task base:environment:show` - **`cli/`** — wraps TypeScript CLI commands; exposes `task cli:build`, `task cli:validate`, `task cli:scaffold` - **`validator/`** — pure-shell skill validator (no Node.js); exposes `task validator:execute` ## Workflow ### Step 1 — Gather domain context Before writing anything: - Understand **what** the skill does and **when** it should activate - Collect real, specific knowledge — runbooks, API docs, code examples, past corrections - Generic knowledge produces generic skills; domain-specific input produces valuable skills ### Step 2 — Create the skill directory and SKILL.md Use `assets/SKILL-template.md` as the starting point. Copy it to `.agents/skills//SKILL.md`. Read `references/specification.md` for complete frontmatter rules (name, description, license, compatibility, metadata, allowed-tools). **Critical:** the `name` field must exactly match the parent directory name. ### Step 3 — Write an effective description The `description` field is the sole activation trigger — agents read only `name` + `description` at startup. Rules: - 1–1024 characters - Cover both **what it does** and **when to use it** - Use imperative phrasing: "Use this skill when…" - Be explicit about indirect triggers: "even if the user doesn't mention X directly" - Include domain keywords users are likely to use Read `references/specification.md` → "description field" section for examples of good vs. poor descriptions. ### Step 4 — Write the SKILL.md body Write **only what the agent wouldn't know without this skill**: project-specific conventions, non-obvious edge cases, specific APIs to use. Keep `SKILL.md` under 500 lines / 5,000 tokens. Move detailed reference material to `references/` and tell the agent *when* to load each file — not just "see references/ for details." Read `references/best-practices.md` for: - Content principles (add what agent lacks; omit what it knows) - Effective patterns: gotchas sections, output templates, checklists, validation loops - Calibrating prescriptiveness to task fragility ### Step 5 — Add references/ (when SKILL.md grows too large) Create focused files in `references/`. Reference them conditionally in `SKILL.md`: ```markdown Read `references/api-errors.md` if the API returns a non-200 status code. ``` ### Step 6 — Add scripts/ (when agents need to run code) Scripts must: accept input via flags (not interactive prompts), expose `--help`, output structured data (JSON/CSV or YAML) to stdout, use meaningful exit codes, be idempotent. **Scripts folder structure:** - `scripts/Taskfile.yml` — **always required** when `scripts/` exists; maps every operator command to a module - `scripts/src/` — **all source files** (TypeScript, JavaScript, Python, or other languages); never place scripts directly in `scripts/` - `scripts/.scripts/` — shell scripts only: Taskfile → api → lib modules - `scripts/package.json` + `scripts/tsconfig.json` — required when TypeScript is present; use pnpm + tsx for dev **❌ NEVER place script files (`.py`, `.ts`, `.js`, `.sh`) directly in `scripts/`.** Only `Taskfile.yml`, `package.json`, `tsconfig.json`, lockfiles, and `.gitignore` belong at the `scripts/` root level. Source code always goes in a subdirectory: `scripts/src/` (any language) or `scripts/.scripts/` (shell modules). **TypeScript CLI pattern** (follow `src/cli/commands.ts` + `src/actions/` in this skill): 1. CLI dispatcher (`commands.ts`) holds an action registry and routes `--action` to the right module 2. Each action is a directory with one `action.ts` exporting `run(options) → Record` 3. Output is always YAML to stdout; `success: true/false` controls exit code 4. Run dev: `npx tsx src/cli/commands.ts --action [options]` 5. Run via Taskfile: `task -- [options]` Read `references/scripts-guide.md` for: - The full **Taskfile → api → lib** shell module architecture - TypeScript CLI structure diagram, pnpm setup, and agentic design requirements Validate a completed skill: ```bash cd .agents/skills//scripts && task validate -- --skill-dir="/absolute/path/to/skill" ``` ### Step 7 — Add assets/ (templates and data files) Place output format templates, schema files, and lookup tables in `assets/`. Reference them from `SKILL.md` so they load only when needed. ### Step 8 — Add .gitignore (always when scripts/ exists) Every skill with a `scripts/` directory must have `scripts/.gitignore`. Git traverses the tree — one file scoped to where the build output lives is sufficient. Copy `scripts/.gitignore` from this skill as the canonical template (covers `node_modules/`, `dist/`, `.env`, `.venv/`, `.DS_Store`). Read `references/best-practices.md` → ".gitignore conventions" for the full template. ### Step 9 — Deploy the skill Once a skill validates cleanly, deploy it so agents can discover it. Deployment always resolves to **absolute paths** and targets both canonical agent skill directories: - `$HOME/.agents/skills/` - `$HOME/.claude/skills/` **About `$HOME`:** `$HOME` is the shell environment variable holding the current user's home directory — e.g. `/Users/` on macOS, `/home/` on Linux. The deploy action resolves it at runtime via Node's `os.homedir()`, so the same command works for any user on any machine without hard-coding paths. `~` is the shell shorthand for the same directory. ```bash cd /scripts task deploy -- --skill-dir="/absolute/path/to/skill" ``` Rules: - `--skill-dir` may be given as a relative path but is always resolved to an absolute path before deployment - Default mode is **symlink**: an absolute-path symlink is created in each target, so the source (e.g. a git repo) stays the single source of truth and updates propagate automatically - `--mode=copy` copies the skill instead (excluding `node_modules/`, `dist/`, `.git/`) — use for machines where the source repo won't stay available - The deployed name comes from the `name:` field in SKILL.md frontmatter (a mismatch with the directory name is reported as a warning) - Existing symlinks at a destination are replaced; existing **real directories** are only replaced with `--force` - `--targets="dir1,dir2"` overrides the target directories when deploying somewhere non-standard - The action is idempotent — re-running a deploy is always safe ## Validation checklist - [ ] `name` in frontmatter matches directory name exactly - [ ] `name` uses only lowercase letters, numbers, hyphens; no leading/trailing/consecutive hyphens - [ ] `description` is under 1024 characters and covers both what and when - [ ] `SKILL.md` body is under 500 lines - [ ] Large reference material is in `references/` with conditional load instructions - [ ] Scripts (if any) have `--help`, avoid interactive prompts, use structured output - [ ] If `scripts/` exists: `scripts/.gitignore` is present (node_modules/, dist/, .env, .venv/) - [ ] If `scripts/` exists: no source files (`.py`, `.ts`, `.js`, `.sh`) sit directly in `scripts/` — they must be in `scripts/src/` or `scripts/.scripts/` - [ ] Skill is deployed (`task deploy`) so it resolves at `$HOME/.agents/skills/` and `$HOME/.claude/skills/` via absolute paths ## If the skill isn't triggering reliably Read `references/description-optimization.md` for the full description eval loop: designing trigger queries, train/validation splits, computing trigger rates, and the optimization cycle.