Teach Linear Markdown to agents without the skill

CHANGELOG.md

@@ -12,6 +12,7 @@
 
 ### Changed
 
+- CLI help now explains how to create real Linear Markdown mentions and collapsible sections, so an agent driving the CLI without the bundled skill still gets it right. The ten commands that take a Markdown body carry the rule inline (`@name` mentions nobody; a plain Linear URL does) and point at a new `linear markdown` reference, and `team members --json` / `user list --json` say what the `url` field is for
 - `issue mine`, `issue query`, `issue start`, and `team states` now group statuses in the same order as the Linear app: by workflow state type, then by the team's configured position within that type. Issue listings previously ran the order backwards (canceled and done first), and every status list sorted on raw position alone, which stranded a late-positioned status such as an "In Review" at position 1002 after "Duplicate" instead of beside "In Progress"
 - when `--limit` truncates an issue listing, the retained issues are now the most actionable rather than the most recently closed. The Linear API cannot sort by a team's configured positions, so it still selects which issues are fetched; that selection changed from closed-first to open-first. A status this build does not recognize sorts after all known ones
 - an unquoted `$VAR` reference in a `LINEAR_`/`GH_`/`GITHUB_` value is now skipped with a warning rather than expanded. Expansion of an unset variable silently produced the string `"undefined"`, and a self-referential one hung. Quoted values are unaffected, since dotenv never expanded those

skills/linear-cli/SKILL.md

@@ -237,6 +237,8 @@ linear label create
 linear label delete
 linear label list
 
+linear markdown
+
 linear milestone
 linear milestone create
 linear milestone delete
@@ -281,6 +283,7 @@ linear user list
 - [initiative-update](references/initiative-update.md) - Manage initiative status updates (timeline posts)
 - [issue](references/issue.md) - Manage Linear issues
 - [label](references/label.md) - Manage Linear issue labels
+- [markdown](references/markdown.md) - Linear-flavored Markdown: mentions and collapsible sections
 - [milestone](references/milestone.md) - Manage Linear project milestones
 - [project](references/project.md) - Manage Linear projects
 - [project-update](references/project-update.md) - Manage project status updates

skills/linear-cli/references/commands.md

@@ -11,6 +11,7 @@
 - [initiative-update](./initiative-update.md) - Manage initiative status updates (timeline posts)
 - [issue](./issue.md) - Manage Linear issues
 - [label](./label.md) - Manage Linear issue labels
+- [markdown](./markdown.md) - Linear-flavored Markdown: mentions and collapsible sections
 - [milestone](./milestone.md) - Manage Linear project milestones
 - [project](./project.md) - Manage Linear projects
 - [project-update](./project-update.md) - Manage project status updates

skills/linear-cli/references/document.md

@@ -36,7 +36,12 @@ Usage:   linear document create
 
 Description:
 
-  Create a new document
+  Create a new document                                                           
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 
@@ -112,7 +117,12 @@ Usage:   linear document update <documentId>
 
 Description:
 
-  Update an existing document
+  Update an existing document                                                     
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 

skills/linear-cli/references/initiative-update.md

@@ -33,7 +33,12 @@ Usage:   linear initiative-update create <initiativeId>
 
 Description:
 
-  Create a new status update for an initiative
+  Create a new status update for an initiative                                    
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 

skills/linear-cli/references/issue.md

@@ -152,7 +152,12 @@ Usage:   linear issue comment add [issueId]
 
 Description:
 
-  Add a comment or reply; images uploaded with --attach render inline
+  Add a comment or reply; images uploaded with --attach render inline             
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 
@@ -205,7 +210,12 @@ Usage:   linear issue comment update <commentId>
 
 Description:
 
-  Update an existing comment
+  Update an existing comment                                                      
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 
@@ -241,7 +251,12 @@ Usage:   linear issue create
 
 Description:
 
-  Create a linear issue
+  Create a linear issue                                                           
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 
@@ -394,13 +409,16 @@ Description:
 
 Options:
 
-  -h, --help             - Show this help.                                                         
-  --workspace  <slug>    - Target workspace (uses credentials)                                     
-  --base       <branch>  - The branch into which you want your code merged                         
-  --draft                - Create the pull request as a draft                                      
-  -t, --title  <title>   - Optional title for the pull request (Linear issue ID will be prefixed)  
-  --web                  - Open the pull request in the browser after creating it                  
-  --head       <branch>  - The branch that contains commits for your pull request
+  -h, --help                - Show this help.                                                               
+  --workspace     <slug>    - Target workspace (uses credentials)                                           
+  --base          <branch>  - The branch into which you want your code merged                               
+  --draft                   - Create the pull request as a draft                                            
+  -t, --title     <title>   - Optional title for the pull request (Linear issue ID will be prefixed)        
+  --web                     - Open the pull request in the browser after creating it                        
+  --head          <branch>  - The branch that contains commits for your pull request                        
+  -T, --template  <file>    - Start the pull request body from this template file (the Linear issue URL is  
+                              appended)                                                                     
+  --no-template             - Ignore the pr_template config option for this pull request
 ```
 
 ### query
@@ -567,7 +585,12 @@ Usage:   linear issue update [issueId]
 
 Description:
 
-  Update a linear issue
+  Update a linear issue                                                           
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 

skills/linear-cli/references/markdown.md

@@ -0,0 +1,57 @@
+# markdown
+
+> Linear-flavored Markdown: mentions and collapsible sections
+
+## Usage
+
+```
+Usage:   linear markdown
+
+Description:
+
+  Linear-flavored Markdown: mentions and collapsible sections                  
+
+  These rules apply to comment bodies, issue descriptions, document content,   
+  project overviews, and status update bodies.                                 
+
+  MENTIONS                                                                     
+
+  A resource's plain Linear URL becomes a linked mention. A literal `@name`, an
+  `@[Name](id)`, or a Markdown link such as `[Name](url)` does not — it stays  
+  plain text and notifies nobody. Put the bare URL in the body:                
+
+  https://linear.app/acme/profiles/someuser can you take a look?               
+
+  RESOLVING PEOPLE                                                             
+
+  Look the person up in the relevant team first. The team can usually be       
+  inferred from the issue identifier or the current directory:                 
+
+  linear team members ENG --json                                               
+
+  Paste the selected member's `url` field verbatim. If the intended person is  
+  not a member of that team, stop and confirm before searching the whole       
+  workspace with `linear user list --json`; mentioning someone outside the team
+  is likely accidental.                                                        
+
+  To mention an issue, use its URL the same way:                               
+
+  linear issue url ENG-123                                                     
+
+  COLLAPSIBLE SECTIONS                                                         
+
+  Open a section with `+++ [title]` and close it with `+++`:                   
+
+  +++ [Server log]                                                             
+
+  Markdown content that is initially hidden.                                   
+
+  +++                                                                          
+
+  The square brackets around the title and the closing `+++` are both required.
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)
+```

skills/linear-cli/references/project-update.md

@@ -33,7 +33,12 @@ Usage:   linear project-update create <projectId>
 
 Description:
 
-  Create a new status update for a project
+  Create a new status update for a project                                        
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 

skills/linear-cli/references/project.md

@@ -36,7 +36,12 @@ Usage:   linear project create
 
 Description:
 
-  Create a new Linear project
+  Create a new Linear project                                                     
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 
@@ -113,7 +118,12 @@ Usage:   linear project update <projectId>
 
 Description:
 
-  Update a Linear project
+  Update a Linear project                                                         
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
 
 Options:
 

skills/linear-cli/references/team.md

@@ -136,10 +136,10 @@ Description:
 
 Options:
 
-  -h, --help           - Show this help.                      
-  --workspace  <slug>  - Target workspace (uses credentials)  
-  -a, --all            - Include inactive members             
-  -j, --json           - Output as JSON
+  -h, --help           - Show this help.                                                         
+  --workspace  <slug>  - Target workspace (uses credentials)                                     
+  -a, --all            - Include inactive members                                                
+  -j, --json           - Output as JSON; a member's url mentions them when pasted into Markdown
 ```
 
 ### states

skills/linear-cli/references/user.md

@@ -36,8 +36,10 @@ Description:
 
 Options:
 
-  -h, --help           - Show this help.                      
-  --workspace  <slug>  - Target workspace (uses credentials)  
-  -a, --all            - Include inactive members             
-  -j, --json           - Output as JSON
+  -h, --help           - Show this help.                                                               
+  --workspace  <slug>  - Target workspace (uses credentials)                                           
+  -a, --all            - Include inactive members                                                      
+  -j, --json           - Output as JSON; a member's url mentions them when pasted into Markdown. This  
+                         searches the whole workspace — prefer `linear team members <TEAM>`, and       
+                         confirm before mentioning someone outside the team
 ```

src/cli.ts

@@ -16,6 +16,7 @@ import { documentCommand } from "./commands/document/document.ts"
 import { configCommand } from "./commands/config.ts"
 import { schemaCommand } from "./commands/schema.ts"
 import { apiCommand } from "./commands/api.ts"
+import { markdownCommand } from "./commands/markdown.ts"
 import { setCliWorkspace } from "./config.ts"
 
 // Import config and credentials setup
@@ -72,3 +73,4 @@ Environment Variables:
   .alias("configure")
   .command("schema", schemaCommand)
   .command("api", apiCommand)
+  .command("markdown", markdownCommand)

src/commands/document/document-create.ts

@@ -19,6 +19,7 @@ import {
   resolveDocumentTarget,
   toDocumentTargetInput,
 } from "./attachment-target.ts"
+import { withMarkdownHint } from "../../utils/markdown-help.ts"
 
 /**
  * Read content from stdin if available (piped input, with timeout)
@@ -47,7 +48,7 @@ async function readContentFromStdin(): Promise<string | undefined> {
 
 export const createCommand = new Command()
   .name("create")
-  .description("Create a new document")
+  .description(withMarkdownHint("Create a new document"))
   .alias("c")
   .option("-t, --title <title:string>", "Document title (required)")
   .option("-c, --content <content:string>", "Markdown content (inline)")

src/commands/document/document-update.ts

@@ -19,6 +19,7 @@ import {
   resolveDocumentTarget,
   toDocumentTargetInput,
 } from "./attachment-target.ts"
+import { withMarkdownHint } from "../../utils/markdown-help.ts"
 
 const GetDocumentForEdit = gql(`
   query GetDocumentForEdit($id: String!) {
@@ -177,7 +178,7 @@ async function readContentFromStdin(): Promise<string | undefined> {
 
 export const updateCommand = new Command()
   .name("update")
-  .description("Update an existing document")
+  .description(withMarkdownHint("Update an existing document"))
   .alias("u")
   .arguments("<documentId:string>")
   .option("-t, --title <title:string>", "New title for the document")

src/commands/initiative-update/initiative-update-create.ts

@@ -11,6 +11,7 @@ import {
 } from "../../utils/errors.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
+import { withMarkdownHint } from "../../utils/markdown-help.ts"
 
 const HEALTH_VALUES = ["onTrack", "atRisk", "offTrack"] as const
 type HealthValue = (typeof HEALTH_VALUES)[number]
@@ -98,7 +99,7 @@ async function resolveInitiativeId(
 
 export const createCommand = new Command()
   .name("create")
-  .description("Create a new status update for an initiative")
+  .description(withMarkdownHint("Create a new status update for an initiative"))
   .alias("c")
   .arguments("<initiativeId:string>")
   .option("--body <body:string>", "Update content (markdown)")

src/commands/issue/issue-comment-add.ts

@@ -12,6 +12,7 @@ import {
 } from "../../utils/upload.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
+import { withMarkdownHint } from "../../utils/markdown-help.ts"
 
 // Linear documents CommentCreateInput.id as "The identifier in UUID v4 format".
 const UUID_V4_REGEX =
@@ -20,7 +21,9 @@ const UUID_V4_REGEX =
 export const commentAddCommand = new Command()
   .name("add")
   .description(
-    "Add a comment or reply; images uploaded with --attach render inline",
+    withMarkdownHint(
+      "Add a comment or reply; images uploaded with --attach render inline",
+    ),
   )
   .arguments("[issueId:string]")
   .option("-b, --body <text:string>", "Comment body text")

src/commands/issue/issue-comment-update.ts

@@ -3,10 +3,11 @@ import { Input } from "@cliffy/prompt"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
+import { withMarkdownHint } from "../../utils/markdown-help.ts"
 
 export const commentUpdateCommand = new Command()
   .name("update")
-  .description("Update an existing comment")
+  .description(withMarkdownHint("Update an existing comment"))
   .arguments("<commentId:string>")
   .option("-b, --body <text:string>", "New comment body text")
   .option(