Skip to content

SKILL.md: todo/card/document content IS Markdown-converted, docs say otherwise #674

Description

@apokalipto

Summary

skills/basecamp/SKILL.md (v0.9.1, line 98) tells agents that todo content is sent
as-is:

For todos, documents, and cards, content is sent as-is — use plain text or HTML directly.

This is not what the CLI does. Todo descriptions are Markdown-converted, and have
been for a while — internal/commands/todos.go calls richtext.MarkdownToHTML(description)
before building the request. The same conversion is applied in cards.go and files.go,
the other two types the line names.

Line 93, just above, was updated for 0.9 to mention tables — so this area was revised
recently and line 98 appears to have been missed.

Why it matters

This is agent-facing documentation, and the guidance is actively harmful: an agent that
follows it hand-writes HTML for todo descriptions. That is more work, more error-prone,
and it silently disables the Markdown path — IsHTML() short-circuits the whole field,
so the agent also loses inline image upload, which only works via Markdown
![alt](/local/path) syntax.

I hit this directly: I wrote a workflow skill around the documented behaviour, then found
the real behaviour contradicted it on a live project.

Reproduction

CLI 0.9.1, macOS arm64.

basecamp todos create "nesting test" --in <project> --list <list> --description \
'Markdown check:

- Level 1
    - Level 2
        - Level 3

| Field | Type |
| --- | --- |
| name | string |

```ruby
class Client < ApplicationRecord
end

'


Reading the stored description back with `basecamp todos show <id> --agent`:

```html
<ul dir="auto">
<li>Level 1
<ul>
<li>Level 2
<ul>
<li>Level 3</li>
</ul>
...
<table>...</table>
<pre language="ruby" data-language="ruby" data-controller="syntax-highlight"><code>...</code></pre>

Nested lists, tables, fenced code and inline images all render correctly from Markdown —
the opposite of what line 98 says.

Suggested fix

Drop or invert line 98. Something like:

Markdown is converted to HTML for todos, cards, documents, messages, comments, chat,
check-ins and schedule entries. Raw HTML is also accepted and passes through unchanged,
but it is all-or-nothing per field — a field containing any HTML tag skips Markdown
conversion entirely, including inline image upload.

Happy to send a PR if that wording works.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions