feat: add Agent Skills for project and issue management

[iamfj]

Summary

Add a skills/ directory to the linearis repo containing Agent Skills (agentskills.io spec) that teach AI agents how to use linearis effectively. Published on skills.sh via npx skills add czottmann/linearis@<skill-name>.

Motivation

Linearis is designed for AI agents, but agents still need to discover how to use it. Currently, the README has an example prompt, but the Agent Skills ecosystem (skills.sh, npx skills) is the standard way agents discover and load tool-specific workflows on demand.

Current landscape on skills.sh

Skill	Installs	Gap
schpet/linear-cli@linear-cli	2.4K	Different CLI tool
openai/skills@linear	1.3K	Generic Linear, not linearis
lobehub/lobehub@linear	383	LobeHub-specific

No linearis-specific skills exist. The czottmann/linearis namespace is the most credible source for official skills.

Proposed Skills

Three focused skills, matching linearis's own discover-then-act pattern (small context, load only what you need):

1. linearis-issue-workflow

Trigger: Creating, updating, searching, triaging, or tracking Linear issues.

Covers:

• Full issue lifecycle: create → assign → label → status update → close
• Triage patterns: search → prioritize → assign → label → comment
• Issue relations: blocks, blocked-by, relates-to, parent-child
• File operations: upload → get URL → embed in comment/description
• Comments on issues
• Label and assignee management

2. linearis-sprint-planning

Trigger: Sprint/cycle planning, milestone tracking, release management.

Covers:

• Listing and reading cycles (--active, --window)
• Milestone CRUD within projects
• Assigning issues to cycles
• Sprint progress overview patterns

3. linearis-docs

Trigger: Creating or managing Linear documents, linking docs to projects/issues.

Covers:

• Document CRUD (create, list, read, update, delete)
• Linking documents to projects and issues
• Knowledge base organization patterns

Design Decisions

• No dedicated setup skill. Each skill includes an inline auth guard: "Run linearis usage. If it fails, run linearis auth login first."
• Light cross-references between skills (e.g., sprint-planning mentions issue-workflow exists) but each skill is self-contained — overlapping commands are repeated inline so agents never need to load two skills for one task.
• Token-efficient. Skills leverage linearis's usage → <domain> usage → execute pattern. Each skill stays under 500 words.
• Lives in the main repo under skills/ — ships with the tool, single source of truth, versioned together.

Repo Structure

skills/
├── linearis-issue-workflow/
│   └── SKILL.md
├── linearis-sprint-planning/
│   └── SKILL.md
└── linearis-docs/
    └── SKILL.md

Installation (for users)

npx skills add czottmann/linearis@linearis-issue-workflow
npx skills add czottmann/linearis@linearis-sprint-planning
npx skills add czottmann/linearis@linearis-docs

Publishing Requirements

Skills follow the Agent Skills specification:

• SKILL.md with YAML frontmatter (name, description, optional license, compatibility)
• name: lowercase, hyphens, must match directory name
• description: max 1024 chars, describes what it does + when to use it
• Compatible with: Claude Code, pi, Codex, and any agent supporting the Agent Skills standard
• skills.sh discovers skills automatically once installed via npx skills add

Acceptance Criteria

• skills/ directory with 3 subdirectories, each containing a valid SKILL.md
• All skills pass npx skills validation (valid frontmatter, name matches directory)
• Each skill includes inline auth prerequisite check
• Light cross-references between skills where relevant
• Each skill is self-contained (works without loading other skills)
• Skills reference actual linearis commands with correct flags
• Installable via npx skills add czottmann/linearis@<name>