home-v1-skills-code-agent/skill-manager
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add skill-manager skill (migrated from skill-creator) with deploy action

Browse Source 
- Skill content moved from ~/.agents/skills/skill-creator, renamed to skill-manager
- New deploy CLI action: installs any skill via absolute-path symlinks (or copies)
  into $HOME/.agents/skills, $HOME/.claude/skills and $HOME/.cline/skills
- Taskfile + shell module wrappers (task deploy / cli:deploy)
- SKILL.md: deploy docs, origin-repository/origin-path metadata

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
oleg-lukasonok
2026-07-23 22:32:42 +03:00
co-authored by Claude Fable 5
parent cc30987dd2
commit 6042272ccc
62 changed files with 3474 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+242
View File
@@ -0,0 +1,242 @@
---
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, $HOME/.cline/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, $HOME/.claude/skills and $HOME/.cline/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>`
- `$HOME/.cline/skills/<skill-name>`
```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>`, `$HOME/.claude/skills/<name>` and `$HOME/.cline/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.