Skill Manage

Skill Manage

Use this skill to create, patch, pin, unpin, rename, or archive managed skills. It does not promote skills into the user-authored namespace.

The guarded writer only lands files under agent-authored paths:

• Telegram/private agent: .claude/skills/agent/telegram/<name>/SKILL.md
• Social persona target: .claude/skills/agent/social/<service-id>/<name>/SKILL.md

Never write .claude/skills/<name>/ directly. That namespace is user-authored.

Create

Pipe the complete SKILL.md body through stdin:

pnpm dev maintenance skill-manage create \
  --persona telegram \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --json <<'EOF'
---
name: <skill-name>
description: Use when ...
allowed-tools:
  - Read
---

# <Title>

Instructions.
EOF

To create a skill for a social service, target the service path but keep the caller private:

pnpm dev maintenance skill-manage create \
  --persona social \
  --service-id xtwitter \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --json <<'EOF'
---
name: <skill-name>
description: Use when ...
allowed-tools:
  - Read
---

# <Title>

Instructions.
EOF

New social-targeted skills are not usable by the social runtime until the operator adds the skill name to that service's allowedSkills config.

Patch

Patch replaces the complete SKILL.md body for an existing managed skill. Pass the current SKILL.md SHA-256 with --expected-sha256; stale edits fail closed.

pnpm dev maintenance skill-manage patch \
  --persona telegram \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --expected-sha256 <current-skill-md-sha256> \
  --json <<'EOF'
---
name: <skill-name>
description: Use when ...
allowed-tools:
  - Read
---

# <Title>

Updated instructions.
EOF

Archive

Archive moves an existing managed skill under the persona-local archived/ directory after snapshotting the active tree. It requires the current SKILL.md SHA-256.

pnpm dev maintenance skill-manage archive \
  --persona telegram \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --expected-sha256 <current-skill-md-sha256> \
  --json

Pin And Unpin

Pin protects a managed skill from archive and rename while still allowing content patches. Unpin removes the marker. Both commands require the current SKILL.md SHA-256.

pnpm dev maintenance skill-manage pin \
  --persona telegram \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --expected-sha256 <current-skill-md-sha256> \
  --json

pnpm dev maintenance skill-manage unpin \
  --persona telegram \
  --name <skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --expected-sha256 <current-skill-md-sha256> \
  --json

Rename

Rename moves an existing managed skill to a new managed name and rewrites only the frontmatter name: field. Body text, examples, and headings are left unchanged. It requires the current SKILL.md SHA-256.

pnpm dev maintenance skill-manage rename \
  --persona telegram \
  --name <old-skill-name> \
  --new-name <new-skill-name> \
  --actor-tier WRITE_LOCAL \
  --user-id <request-user-id> \
  --expected-sha256 <current-skill-md-sha256> \
  --json

Guardrails

• SOCIAL callers are rejected by the command.
• Names must match ^[a-z0-9-]{1,63}$.
• archived is reserved and cannot be used as a managed skill name.
• SKILL.md must be 64 KB or smaller.
• The scanner runs on a temp copy before the real file lands.
• Patch replaces the full SKILL.md; it does not apply partial diffs.
• Patch, archive, pin, unpin, and rename require --expected-sha256.
• Pinned or malformed-pin-marker skills cannot be archived or renamed; unpin removes only the marker path.
• Rename rewrites only frontmatter name: and fails on name collisions across loaded skill roots.
• If a process is interrupted mid-rename, inspect hidden .telclaude-rename-*.tmp-* or .telclaude-rename-*.bak-* directories under the persona path before retrying.
• Archive moves skills to agent/<persona>/archived/ so normal persona loading ignores them.
• The command snapshots the whole skill tree before writing, patching, pinning, unpinning, renaming, or archiving.
• Every attempt is written to the skill-manage audit log.
• Bash examples must avoid shell chaining, pipes, redirection, command substitution, and process substitution.
• Secret names, secret-looking values, private URLs, metadata URLs, and sensitive host filesystem paths are rejected.
• Use neutral credential placeholders such as <provider-token-placeholder>, sk-..., ghp_xxxxxxxxxxxxxxxxxxxx, example-token-placeholder, or redacted; do not include realistic provider tokens, bearer tokens, cookies, sessions, or infrastructure secret environment names.