# Improve Description > Improve Description - Skill: `cyberuni/improve-description` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add cyberuni/improve-description` - Raw SKILL.md: https://api.skillmd.com/api/skills/cyberuni/improve-description/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cyberuni (https://skillmd.com/u/cyberuni) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cyberuni/improve-description --- # Improve Description ## When to use - The user wants an existing description tidied up — stray blank lines, typos, broken formatting, a wall of unpunctuated text. - The user wants a description written or restructured as rich text. - Recovering from `Asana API error: XML is invalid` (or `Rich text should be wrapped in tag`). Plain prose with no formatting needs no HTML — use `--notes` / `notes` instead. ## Instructions ### 1. Read the current description ```sh cyber-asana task get --json ``` Always edit from `html_notes`. `task get` and `asana_task_get` return it unconditionally — an empty description comes back as ``, never absent — so there is no case where you need the plain-text `notes` projection, which drops every link and list. ### 2. Clean it up — light by default **The default is a copy-edit, not a rewrite.** Preserve the author's message, wording, and structure. The result should read as the same person's text with the noise removed. Do: - Collapse runs of three or more blank lines to one. - Strip trailing whitespace and stray leading indentation. - Fix obvious typos and misspellings. - Fix punctuation and capitalization that are plainly wrong. - Repair broken markup — an unclosed tag, a list where some items are `-` and others `*`, a heading that lost its marker. - Split a run-on wall of text at sentence boundaries the author clearly intended. - Turn an existing dash-or-number list into a real `

` citations. Never cite a source you did not read. Flag any claim you could not support instead of quietly dropping it. | A template modifier is the only reason to add or reorder sections. When it moves content, move it — do not paraphrase it on the way. ### 4. Write it back Wrap the whole document in a bare `` — required, and it must carry no attributes. ```sh cyber-asana task update --html-notes '

Summary

Ship the thing.' ``` MCP: pass `html_notes` to `asana_task_create` / `asana_task_update` (or `asana_project_update`). `--notes` and `--html-notes` are mutually exclusive; the same holds for `notes` and `html_notes`. Read the task back afterward — Asana normalizes on save (``→``, `` stripped to text, list attributes dropped), so what you sent is not always what is stored. ## Asana's HTML subset Verified against the live Asana API (`PUT /tasks/{gid}`, 2026-08). **Supported** | Tag | Notes | | --- | --- | | `` | Required outermost wrapper, no attributes | | `
` `
` `
` | Headings — `
`–`

` are rejected | | `` `` `` `` | `` → ``, `` → `` on save | | `` | Inline code | | `` | Code block; `data-language` attribute is kept | | `` `` `` | Nesting allowed, including `` inside `` | | `` | `href` (or `data-asana-gid`) required; absolute URL only | | `` | Multi-line allowed | | `` `` `` | ` ` is rejected — use ` ` for the header row | | ` ` | Normalized to `` | | `` | Highlight; Asana injects its own color attributes | **Rejected — these are what produce `XML is invalid`** `` · ` ` · ` ` · ``–` ` · `` · `` · `_{` · `^{` · `}} ` · `` outside a list `` is accepted but silently stripped to its text. `` nested together fails with an opaque *"unexpected error occurred"* — use `` alone. ### Line breaks are literal newlines There is no `` and no ` `. Separate blocks with real newline characters inside ``; Asana preserves them. A cleanup pass therefore collapses runs of blank lines rather than deleting them. ```html Summary First paragraph. Second paragraph. ``` Passing `html_notes` via MCP avoids shell quoting entirely and is the safer path for multi-line content. From a POSIX shell, use a quoted heredoc so the newlines survive: ```sh cyber-asana task update --html-notes "$(cat <<'HTML' Summary Ship the thing. HTML )" ``` ### Escape `<`, `>` in text A raw `<` or `>` outside a tag is rejected with `Malformed rich text. Found < or > that was not part of tag.` Escape them as `<` / `>` everywhere — including inside `` and ``, which do **not** suppress parsing. ```html <h2>Title</h2> ``` `&` may be written raw; Asana normalizes it to `&`, in text and in `href` alike. Every tag must be closed — an unclosed `` is rejected. ## Markdown → Asana HTML | Markdown | Asana | | --- | --- | | `# H1` / `## H2` / `### H3` | `` / ` ` / ` ` | | `#### H4` and deeper | Flatten to ` `, or `` on its own line | | Paragraph break | Blank line (literal newline), never `` | | `**bold**` / `*italic*` | `` / `` | | `` `code` `` | `` | | ```` ```ts ... ``` ```` | ` … `, contents escaped | | `- item` / `1. item` | `… ` / `…` | | `[text](url)` | `text` — absolute URL only | | `> quote` | `` | | `---` | `` | | `- [ ] todo` | `☐ todo` — checklist markup is stripped | ## Troubleshooting A rejected update writes nothing — the stored description is left byte-identical. Fix the HTML and retry; there is nothing to recover. | Error | Cause | | --- | --- | | `Rich text should be wrapped in tag.` | Missing ``, or `` carries an attribute | | `XML is invalid` | An unsupported tag — check ``, ` `, ` `, ``+, `` | | `XML is invalid: Malformed rich text. Found < or > that was not part of tag.` | Unescaped `<` or `>` in text | | `XML is invalid: Malformed rich text. XML tag was not closed.` | Unclosed tag | | `One of data-asana-gid or href is required in anchor attributes` | `` with no `href` | | `invalid protocol in HREF field` | Relative or non-http(s) `href` | | `Oops! An unexpected error occurred…` | `` nested inside `` | ## References - `references/templates.md` — PRD, research-note, and bug-report skeletons. Load only when the user asks for a named template (step 3).

Summary

` `

` `

` | Headings — `

`–`

`–`

` · `` · `` · `` · `` · `

Summary

Summary

` / `

` / `

` | | `#### H4` and deeper | Flatten to `

` · `` · `` · `_{` · `^{` · `}}