skill-manager/SKILL.md

---
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-name>/
├── 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
    │   └── <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, -<action>.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/<skill-name>/`

## 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-name>/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-name>/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<string, unknown>`
3. Output is always YAML to stdout; `success: true/false` controls exit code
4. Run dev: `npx tsx src/cli/commands.ts --action <name> [options]`
5. Run via Taskfile: `task <name> -- [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/<skill-name>/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/<skill-name>`
- `$HOME/.claude/skills/<skill-name>`

**About `$HOME`:** `$HOME` is the shell environment variable holding the current user's
home directory — e.g. `/Users/<username>` on macOS, `/home/<username>` 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 <skill-manager>/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/<name>` and `$HOME/.claude/skills/<name>` 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.