From 3b8204e1d7d1f3614f67ffdf503cfffe1f95ed43 Mon Sep 17 00:00:00 2001 From: Alan Pope Date: Thu, 12 Mar 2026 09:44:26 +0000 Subject: [PATCH] feat: improve skill scores for linear-cli MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hullo @schpet 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | linear-cli | 54% | 100% | +46% | | release | 0% | 100% | +100% |
Changes made **linear-cli skill** (`skills/linear-cli/SKILL.md` + `SKILL.template.md`): - Expanded frontmatter description with specific actions (create, update, list, search, close), explicit "Use when..." trigger clause, and natural user phrases like "create a Linear issue", "list my tickets", "add a comment on ENG-123" - Condensed the "Why use file-based flags" explanation from a 4-bullet list to a single line — the example already demonstrates the point - Note: since `SKILL.md` is auto-generated from `SKILL.template.md`, both files were updated to stay in sync. You'll want to apply similar changes to the template so they persist through `deno task generate-skill-docs` runs **release skill** (`.claude/skills/release/SKILL.md`): - Fixed `name: Release` → `name: release` (validation requires lowercase with hyphens only) - Removed `version: 0.1.0` from frontmatter (unknown key that triggered a validation warning) - Rewrote description with specific actions and "Use when..." trigger clause - Removed redundant "When to Use" and "Prerequisites" sections (already covered by the description and discoverable by the agent) - Consolidated "Important Notes" into the skill header where they're immediately visible - Removed "Post-Release" section (generic verification steps the agent can handle)
Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@popey](https://github.com/popey) - if you hit any snags. Thanks in advance 🙏 --- .claude/skills/release/SKILL.md | 38 +++-------------------------- skills/linear-cli/SKILL.md | 9 ++----- skills/linear-cli/SKILL.template.md | 9 ++----- 3 files changed, 7 insertions(+), 49 deletions(-) diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 6edca88d..43ad8d00 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -1,27 +1,11 @@ --- -name: Release -description: This skill should be used when the user asks to "make a release", "create a release", "cut a release", "release a new version", "publish a release", or mentions preparing for release. Provides comprehensive workflow for reviewing changes, updating changelog, determining semver bump, and publishing. -version: 0.1.0 +name: release +description: Create and publish linear-cli releases with changelog management, semver version bumping, and git tagging. Use when the user says "make a release", "cut a release", "publish a new version", "release linear-cli", "bump version", or "tag a release". Handles reviewing commits, adding changelog entries, running quality checks, updating version files, and pushing tags. --- # Release Workflow -This skill provides a systematic workflow for creating and publishing releases for the linear-cli project. It handles changelog management, version bumping, testing, and tagging. - -## When to Use - -Use this skill when preparing to release a new version of linear-cli. The workflow ensures all changes are documented, tests pass, and versions are properly tagged before publishing. - -## Prerequisites - -Ensure the following tools are available: - -- `changelog` skill for changelog management -- `svbump` for version bumping (installed) -- `jj` for version control operations -- `just` for running the release tasks - -## Release Workflow +Use `jj` for all version control operations. Use `--ignore-working-copy` for read-only jj operations. Both `jj git push` (bookmark) and `git push origin --tags` (tags) are needed for pushing. ### Step 1: Review Commits Since Last Release @@ -195,22 +179,6 @@ If any step fails: Always stop and report errors clearly. Never continue the release process if a critical step fails. -## Important Notes - -- The justfile `tag` recipe handles the complete process from line 5-21 -- Use `jj` for all version control operations (per project CLAUDE.md) -- Always use `--ignore-working-copy` for read-only jj operations -- The workflow creates a commit on the parent (@-) and then creates a new working commit -- Both `jj git push` and `git push origin --tags` are needed (jj for bookmark, git for tags) - -## Post-Release - -After successful release: - -1. Verify the tag appears on GitHub -2. Check that GitHub Actions release workflow triggers (if configured) -3. Confirm the new version is published - ## Reference See `justfile` lines 5-21 for the complete tag recipe implementation. diff --git a/skills/linear-cli/SKILL.md b/skills/linear-cli/SKILL.md index 2812806f..9c815856 100644 --- a/skills/linear-cli/SKILL.md +++ b/skills/linear-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: linear-cli -description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management. +description: Create, update, list, search, and close Linear issues, projects, cycles, and initiatives from the command line. Use when the user wants to interact with Linear — e.g. "create a Linear issue", "list my tickets", "update issue status", "add a comment on ENG-123", "search Linear for onboarding", or "query the Linear API". Supports issue management, project tracking, label assignment, milestone updates, and raw GraphQL queries via the linear CLI. allowed-tools: Bash(linear:*), Bash(curl:*) --- @@ -26,12 +26,7 @@ When working with issue descriptions or comment bodies that contain markdown, ** - Use `--description-file` for `issue create` and `issue update` commands - Use `--body-file` for `comment add` and `comment update` commands -**Why use file-based flags:** - -- Ensures proper formatting in the Linear web UI -- Avoids shell escaping issues with newlines and special characters -- Prevents literal `\n` sequences from appearing in markdown -- Makes it easier to work with multi-line content +File-based flags avoid shell escaping issues and ensure proper markdown formatting in Linear. **Example workflow:** diff --git a/skills/linear-cli/SKILL.template.md b/skills/linear-cli/SKILL.template.md index 0d2294b0..f1f4f6bb 100644 --- a/skills/linear-cli/SKILL.template.md +++ b/skills/linear-cli/SKILL.template.md @@ -1,6 +1,6 @@ --- name: linear-cli -description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management. +description: Create, update, list, search, and close Linear issues, projects, cycles, and initiatives from the command line. Use when the user wants to interact with Linear — e.g. "create a Linear issue", "list my tickets", "update issue status", "add a comment on ENG-123", "search Linear for onboarding", or "query the Linear API". Supports issue management, project tracking, label assignment, milestone updates, and raw GraphQL queries via the linear CLI. allowed-tools: Bash(linear:*), Bash(curl:*) --- @@ -26,12 +26,7 @@ When working with issue descriptions or comment bodies that contain markdown, ** - Use `--description-file` for `issue create` and `issue update` commands - Use `--body-file` for `comment add` and `comment update` commands -**Why use file-based flags:** - -- Ensures proper formatting in the Linear web UI -- Avoids shell escaping issues with newlines and special characters -- Prevents literal `\n` sequences from appearing in markdown -- Makes it easier to work with multi-line content +File-based flags avoid shell escaping issues and ensure proper markdown formatting in Linear. **Example workflow:**