skill-manager/SKILL.md

name, description, license, metadata, compatibility

name	description	license	metadata	compatibility
skill-manager	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".	Proprietary	author version spec origin-repository origin-path workspace-swiss-knife 1.0 agentskills.io/specification git@github.ibm.com:CTOTools-skills-code-agent/skill-manager.git $HOME/projects-ibm/cognitive-architect/workspace-skills-code-agent/skill-manager	Designed for Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments

Skill Manager

Build, manage, and deploy well-formed Agent Skills — 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:

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:

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:

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:

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.

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.