@cleocode/skills 2.0.0

package/skills/ct-skill-creator/manifest-entry.json

@@ -0,0 +1,17 @@
+{
+  "name": "ct-skill-creator",
+  "version": "1.0.0",
+  "description": "Guide for creating effective CLEO skills with the full v2 standard.",
+  "path": "packages/ct-skills/skills/ct-skill-creator",
+  "status": "active",
+  "tier": 3,
+  "core": false,
+  "category": "meta",
+  "protocol": null,
+  "dependencies": [],
+  "sharedResources": [],
+  "compatibility": ["claude-code", "cursor", "windsurf", "gemini-cli"],
+  "token_budget": 12000,
+  "capabilities": ["skill-creation", "eval-loop", "description-optimization", "quality-eval"],
+  "constraints": ["requires-claude-api-for-eval-loop"]
+}

package/skills/ct-skill-creator/references/dynamic-context.md

@@ -0,0 +1,228 @@
+# Dynamic Context Injection
+
+Skills can inject dynamic runtime information into SKILL.md content before Claude sees it. Three mechanisms are available: shell pre-processing, argument substitution, and session variables.
+
+## Shell Pre-Processing
+
+Embed shell command output directly into skill content using backtick-bang syntax.
+
+**Syntax**: `` !`command` ``
+
+The command runs before Claude sees the skill content. The entire `` !`command` `` expression is replaced with the command's stdout output.
+
+**Examples**:
+
+```markdown
+## Current Repository State
+
+Recent commits:
+!`git log --oneline -5`
+
+Current branch: !`git branch --show-current`
+
+Last tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "no tags"`
+```
+
+After pre-processing, Claude sees:
+
+```markdown
+## Current Repository State
+
+Recent commits:
+a1b2c3d fix: resolve auth timeout
+d4e5f6g feat: add user dashboard
+7h8i9j0 refactor: extract validation
+k1l2m3n docs: update API reference
+o4p5q6r test: add integration tests
+
+Current branch: feature/user-dashboard
+
+Last tag: v2.3.1
+```
+
+**Complex commands** work as expected -- pipes, subshells, and multi-command expressions:
+
+```markdown
+Node version: !`node --version`
+Package name: !`cat package.json | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])"`
+File count: !`find src -name '*.ts' | wc -l`
+```
+
+**Failure behavior**: If a command fails (non-zero exit code), the expression is replaced with an empty string. The skill still loads -- failed commands do not block skill execution. Use fallback patterns like `command || echo "fallback"` to handle expected failures gracefully:
+
+```markdown
+Python version: !`python3 --version 2>/dev/null || echo "Python not installed"`
+```
+
+## Argument Substitution
+
+When users invoke a skill with arguments (e.g., `/my-skill arg1 arg2`), the arguments are available through substitution variables in the skill body.
+
+### Full Argument String
+
+`$ARGUMENTS` -- all arguments as a single string, exactly as the user typed them.
+
+```markdown
+## Task
+
+Analyze the following: $ARGUMENTS
+```
+
+If the user types `/analyze-code src/auth.ts --depth 3`, Claude sees:
+
+```markdown
+## Task
+
+Analyze the following: src/auth.ts --depth 3
+```
+
+### Indexed Access
+
+Access individual arguments by zero-based index:
+
+| Variable | Equivalent | Value (for `/skill foo bar baz`) |
+|---|---|---|
+| `$ARGUMENTS[0]` | `$1` | `foo` |
+| `$ARGUMENTS[1]` | `$2` | `bar` |
+| `$ARGUMENTS[2]` | `$3` | `baz` |
+| `$ARGUMENTS` | (all) | `foo bar baz` |
+
+The `$1`, `$2`, `$3` shorthand forms are interchangeable with `$ARGUMENTS[0]`, `$ARGUMENTS[1]`, `$ARGUMENTS[2]`.
+
+### Worked Example
+
+Given the invocation `/deploy-check production api-gateway`:
+
+```markdown
+## Deployment Check
+
+**Environment**: $1
+**Service**: $2
+
+Run the following verification:
+
+1. Check that $ARGUMENTS[0] cluster is healthy
+2. Verify $ARGUMENTS[1] pods are running
+3. Full command context: deploying $ARGUMENTS
+```
+
+Claude sees:
+
+```markdown
+## Deployment Check
+
+**Environment**: production
+**Service**: api-gateway
+
+Run the following verification:
+
+1. Check that production cluster is healthy
+2. Verify api-gateway pods are running
+3. Full command context: deploying production api-gateway
+```
+
+### Missing Arguments
+
+If a user provides fewer arguments than the skill references, unreferenced `$ARGUMENTS[N]` variables are replaced with empty strings. Design skills defensively by placing critical instructions outside of argument-dependent sections, or by documenting required arguments in `argument-hint`.
+
+## Session Variables
+
+Two environment variables are available for runtime context:
+
+### CLAUDE_SESSION_ID
+
+`${CLAUDE_SESSION_ID}` -- a unique identifier for the current Claude session. Useful for correlating logs, creating session-specific output files, or tracking work across multiple skill invocations within the same session.
+
+```markdown
+## Logging
+
+Write analysis results to `/tmp/analysis-${CLAUDE_SESSION_ID}.json` for later review.
+```
+
+### CLAUDE_SKILL_DIR
+
+`${CLAUDE_SKILL_DIR}` -- the absolute filesystem path to the skill's root directory. This is the directory containing SKILL.md.
+
+This variable is critical for skills that bundle scripts, references, or assets. Without it, bundled scripts would need hardcoded absolute paths -- which break when the skill is installed in different locations (global vs. project, different providers, different machines).
+
+**The portable bundled-script pattern**:
+
+```markdown
+## Analysis
+
+Run the analysis script on the target file:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/analyze.py "$1"
+```
+```
+
+This works regardless of where the skill is installed:
+- Global install: `${CLAUDE_SKILL_DIR}` = `/home/user/.claude/skills/my-skill`
+- Project install: `${CLAUDE_SKILL_DIR}` = `/projects/myapp/.claude/skills/my-skill`
+- Symlinked: `${CLAUDE_SKILL_DIR}` resolves through the symlink to the actual directory
+
+Without `${CLAUDE_SKILL_DIR}`, you would need to hardcode paths like `/home/user/.claude/skills/my-skill/scripts/analyze.py`, which breaks for every other user and installation location.
+
+**Referencing bundled resources**:
+
+```markdown
+For the full API schema, read: ${CLAUDE_SKILL_DIR}/references/api-schema.md
+
+For brand assets, copy from: ${CLAUDE_SKILL_DIR}/assets/logo.png
+```
+
+## Combining All Features
+
+A realistic skill body demonstrating all three injection mechanisms together:
+
+```markdown
+---
+name: pr-review
+description: "Automated pull request code review with project-aware analysis. Use when reviewing PRs, checking code quality, or preparing review comments."
+argument-hint: "<pr-number>"
+allowed-tools:
+  - Read
+  - Bash(gh pr *)
+  - Bash(git *)
+---
+
+# PR Review
+
+## Project Context
+
+**Repository**: !`git remote get-url origin | sed 's/.*github.com[:/]//' | sed 's/.git$//'`
+**Default branch**: !`git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"`
+**Test framework**: !`[ -f vitest.config.ts ] && echo "Vitest" || ([ -f jest.config.js ] && echo "Jest" || echo "unknown")`
+
+## Review Target
+
+Fetch and review PR #$1:
+
+```bash
+gh pr diff $ARGUMENTS[0] > /tmp/pr-${CLAUDE_SESSION_ID}.diff
+```
+
+## Review Checklist
+
+Load the project's review standards:
+
+```bash
+cat ${CLAUDE_SKILL_DIR}/references/review-checklist.md
+```
+
+Run the automated checks:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/lint_diff.py /tmp/pr-${CLAUDE_SESSION_ID}.diff
+```
+
+## Output
+
+Write the review to `/tmp/review-$1-${CLAUDE_SESSION_ID}.md` using the template at `${CLAUDE_SKILL_DIR}/assets/review-template.md`.
+```
+
+In this example:
+- **Shell pre-processing** (`!`...``) injects the repository name, default branch, and test framework at load time
+- **Argument substitution** (`$1`, `$ARGUMENTS[0]`) passes the PR number into commands and filenames
+- **Session variables** (`${CLAUDE_SESSION_ID}`, `${CLAUDE_SKILL_DIR}`) create unique temp files and locate bundled scripts portably

package/skills/ct-skill-creator/references/frontmatter.md

@@ -0,0 +1,83 @@
+# SKILL.md Frontmatter Schema
+
+## Required Fields
+
+```yaml
+name: string           # hyphen-case, max 64 chars, must match directory name
+description: string    # max 1024 chars, no < or >, use quoted strings not >-/| multiline
+```
+
+## Optional Fields
+
+```yaml
+argument-hint: string            # max 100 chars; shown in /name autocomplete
+disable-model-invocation: bool   # true = user-only invoke; description removed from context
+user-invocable: bool             # false = hidden from /menu; Claude still sees description
+allowed-tools: string | list     # pre-approved tools; Bash(pattern) for restricted bash
+model: string                    # model ID override for this skill
+context: "fork"                  # isolated subagent; no conversation history
+agent: string                    # Explore | Plan | general-purpose | <custom>
+hooks: dict                      # PreToolUse | PostToolUse | Stop handlers
+license: string                  # e.g. MIT
+```
+
+## FORBIDDEN in SKILL.md (belongs in manifest.json)
+
+```
+version, tier, core, category, protocol, dependencies, sharedResources,
+compatibility, token_budget, capabilities, constraints, metadata, tags, triggers
+```
+
+## Copy-Paste Template
+
+```yaml
+---
+name: skill-name
+description: "What this skill does and WHEN to use it. Max 1024 chars. Third person."
+# argument-hint: "[optional-arg]"
+# disable-model-invocation: true
+# user-invocable: false
+# allowed-tools: Read, Grep, Glob
+# model: claude-sonnet-4-6
+# context: fork
+# agent: Explore
+# hooks:
+#   PreToolUse:
+#     - matcher: Bash
+#       command: "echo 'invoked' >> /tmp/audit.log"
+# license: MIT
+---
+```
+
+## Invocation Matrix
+
+| Config | User /slash | Claude auto | Description in ctx |
+|--------|------------|-------------|-------------------|
+| (default) | Yes | Yes | Yes |
+| `disable-model-invocation: true` | Yes | No | No |
+| `user-invocable: false` | No | Yes | Yes |
+| Both above | No | No | No |
+
+## YAML Pitfalls
+
+**Use quoted strings for description** — `>-` and `|` fold/preserve newlines unexpectedly:
+```yaml
+# BAD
+description: >-
+  Deploy applications to staging
+  with pre-flight checks.
+
+# GOOD
+description: "Deploy applications to staging with pre-flight checks."
+```
+
+**Booleans must be unquoted:**
+```yaml
+disable-model-invocation: true    # correct
+disable-model-invocation: "true"  # wrong — this is a string
+```
+
+**Quote strings with special chars** (`:` followed by space, `#`, `>`):
+```yaml
+description: "Note: handles edge cases"   # needs quotes due to colon
+```

package/skills/ct-skill-creator/references/invocation-control.md

@@ -0,0 +1,165 @@
+# Invocation Control
+
+This reference covers how to control when and how skills are triggered, including the interaction between `disable-model-invocation`, `user-invocable`, `allowed-tools`, and context budgets.
+
+## Invocation Matrix
+
+The combination of `disable-model-invocation` and `user-invocable` determines how a skill can be triggered:
+
+| Frontmatter | User `/slash` invoke | Claude auto-trigger | Description in context | Body loaded |
+|---|---|---|---|---|
+| (defaults -- neither set) | Yes | Yes | Always | When invoked |
+| `disable-model-invocation: true` | Yes | No | Never | When user invokes |
+| `user-invocable: false` | No | Yes | Always | When Claude auto-triggers |
+| Both set (`true` + `false`) | Error | Error | -- | Invalid combination |
+
+Key observations:
+- **Default behavior** is the most common: the skill appears in the slash menu, Claude can auto-trigger it, and the description is always in context for trigger evaluation.
+- `disable-model-invocation: true` completely hides the skill from Claude. It cannot see the description, cannot reason about it, and cannot trigger it.
+- `user-invocable: false` removes the slash command but keeps the description visible to Claude, allowing autonomous triggering.
+- Setting both is contradictory (hidden from users AND hidden from Claude) and should not be done.
+
+## disable-model-invocation: true
+
+Use this for skills that perform side effects requiring explicit user intent. When set, the skill's description is removed from Claude's context entirely -- Claude does not know the skill exists.
+
+**When to use**:
+- Deployment workflows (staging, production pushes)
+- Git operations with external effects (force push, tag creation)
+- Communication actions (sending emails, Slack messages, creating PRs)
+- Database mutations (migrations, data backfixes)
+- Billing or payment operations
+- Any destructive or hard-to-reverse operation
+
+**Example**:
+
+```yaml
+---
+name: deploy-production
+description: "Deploy the current branch to production with rolling updates, health checks, and automatic rollback on failure. Use for production deployments only."
+disable-model-invocation: true
+argument-hint: "<service-name> [--canary] [--skip-tests]"
+allowed-tools:
+  - Bash(kubectl *)
+  - Bash(helm *)
+---
+```
+
+The user must explicitly type `/deploy-production api-gateway` to trigger this skill. Claude will never suggest or auto-trigger it, because Claude cannot see that it exists.
+
+## user-invocable: false
+
+Use this for background knowledge that Claude should apply autonomously. The skill has no slash command, but Claude reads the description and auto-loads the body when the conversation context matches.
+
+**When to use**:
+- Project coding standards and conventions
+- API schemas and domain models that inform code generation
+- Style guides that should be applied to all generated content
+- Security policies and compliance rules
+- Architecture patterns specific to the project
+
+**Example**:
+
+```yaml
+---
+name: project-conventions
+description: "Project coding conventions including naming standards, import ordering, error handling patterns, and test structure. Apply these conventions when generating or modifying code in this project."
+user-invocable: false
+---
+```
+
+Claude sees the description, recognizes that a code generation task matches, and loads the skill body automatically. No `/project-conventions` slash command exists.
+
+## allowed-tools
+
+Pre-approves specific tools for use during skill execution, bypassing per-use permission prompts. Reduces friction without giving blanket permissions.
+
+### String Format
+
+Comma-separated list of tool names:
+
+```yaml
+allowed-tools: "Read, Write, Edit, Bash(python3 *)"
+```
+
+### List Format
+
+YAML list for clearer multi-tool specifications:
+
+```yaml
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash(npm test *)
+  - Bash(npx vitest *)
+```
+
+### Bash Pattern Restriction
+
+`Bash(pattern)` pre-approves only bash commands matching the glob pattern. The pattern is matched against the full command string.
+
+```yaml
+# Only allow git and npm commands
+allowed-tools:
+  - Bash(git *)
+  - Bash(npm *)
+
+# Only allow Python scripts in the skill's scripts directory
+allowed-tools:
+  - Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/*)
+```
+
+Without a pattern, bare `Bash` pre-approves all bash commands -- use with caution.
+
+## Context Budget
+
+Skills consume context window space at two levels, and understanding the budget is critical for designing skills that coexist well.
+
+### Description Budget
+
+Every trigger-eligible skill's `description` field is loaded into Claude's context at all times. Each description consumes roughly 100-200 tokens. With 15 skills, that is 1,500-3,000 tokens of always-on context.
+
+Implication: keep descriptions concise and trigger-focused. Every word costs tokens across every single conversation.
+
+### Body Budget
+
+When a skill is triggered, its body (everything below the frontmatter) is loaded into context. The body is capped at 2% of the context window, which is approximately 16,000 characters by default.
+
+This cap can be overridden via the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable:
+
+```bash
+# Increase body budget to 32k chars
+export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000
+```
+
+**Practical limit**: keep skill bodies under 500 lines. Use the progressive disclosure pattern -- put core workflow in SKILL.md and detailed reference material in `references/` files that Claude loads on demand.
+
+### Budget-Aware Design
+
+```
+Always loaded (~200 tokens each):
+  skill-1 description
+  skill-2 description
+  ...
+  skill-N description
+
+Loaded on trigger (~2% of context):
+  SKILL.md body
+
+Loaded on demand (no fixed limit):
+  references/detail-a.md
+  references/detail-b.md
+  scripts/tool.py (executed, not loaded)
+```
+
+## Skill Types Summary
+
+| Type | Frontmatter | Use Case |
+|---|---|---|
+| **Task** | (defaults) | Interactive workflows users invoke by name -- code analysis, deployment, file processing |
+| **Background** | `user-invocable: false` | Domain knowledge Claude applies autonomously -- coding standards, schemas, policies |
+| **Protected** | `disable-model-invocation: true` | Side-effect workflows requiring explicit user intent -- deploys, sends, mutations |
+| **Subagent** | `context: fork` | Self-contained tasks that run in isolation -- research, analysis, generation from scratch |

package/skills/ct-skill-creator/references/output-patterns.md

@@ -0,0 +1,86 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+[Overview]
+
+## Key findings
+[Adapt sections based on what you discover]
+
+## Recommendations
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.