markdown writer
- Repo stars 0
- Author repo skills-registry
- Domain
- Documentation
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# SKILL: Markdown Writer
> Purpose: help agents reliably author and review Markdown with correct structure, links, and minimal ambiguity.
> This skill is intended to be used by any agent that creates/edits/reviews `.md` content.
## When to Load This Skill
Load this skill when you:
- Create or edit any `*.md` file
- Write documentation changes (README, guides, design docs)
- Create or update ADRs in `.github/decisions/`
- Maintain repo context files such as `AGENTS.md`, `llms.txt`, or `copilot-instructions.md`
- Create or update `SKILL.md` packages or `.agent.md` prompts (Markdown structure still applies)
- Review documentation as a critic (links, headings, formatting)
---
## Requirements (Must-Haves)
Agents writing or editing Markdown in this repo must satisfy all of the following:
### R1 — Language and permanence
- All committed Markdown must be **English**.
- Avoid time-sensitive phrasing (“today/now”) unless a date is explicitly stated.
### R2 — Document structure
- Exactly one top-level title: a single `# ...` heading.
- Headings are hierarchical and ordered: `#` → `##` → `###` (no skipped levels).
- Headings are unique (avoid duplicates that may break anchors).
### R3 — Links
- Prefer **relative links** for repo files.
- Do not introduce broken links; if you add/change a link, verify the target exists in the workspace.
- Use `/` as a path separator (never `\`).
- Use descriptive link text (avoid dumping raw URLs unless the URL itself is the reference).
### R4 — Anchors
- Avoid deep anchor links unless the section is stable.
- Keep heading titles simple to reduce renderer-specific anchor differences.
### R5 — Code blocks
- Fenced code blocks must be balanced (opening/closing fences match).
- Add a language tag when possible (e.g. `yaml`, `json`, `bash`, `text`).
### R6 — Frontmatter
- Only use YAML frontmatter when the file format expects it.
- If frontmatter exists, it must be valid YAML wrapped in `---` lines.
### R7 — Safety and hygiene
- Do not include secrets, tokens, credentials, or sensitive logs.
- Keep edits minimal: do not rewrite unrelated sections.
### R8 — Lists and readability
- Use `-` for unordered lists.
- Keep bullets short and scannable; avoid deep nesting unless it improves clarity.
### R9 — Tables
- Prefer tables only when they improve comparison; avoid very wide tables (use bullets instead).
---
## Common Markdown Pitfalls (Avoid)
- Broken relative links after renames/moves (always re-check targets).
- Inconsistent heading casing that creates near-duplicates (hurts search and navigation).
- Over-wide tables (hard to read in GitHub; prefer bullets if the table exceeds typical width).
- Copy-pasted logs containing secrets, tokens, or internal URLs.
## Templates (Use When Applicable)
### Documentation page template
```markdown
# <Title>
## Purpose
<What this document is for, in 1–3 sentences>
## Audience
<Who should read this>
## Workflow / Process
1. <Step>
2. <Step>
## References
- <links>
```
### ADR template (minimal)
```markdown
# ADR-XXXX — <Title>
## Status
Proposed | Accepted | Superseded by ADR-YYYY
## Context
<Why we needed to decide>
## Decision
<What we decided, one sentence>
## Consequences
<What changes; what becomes easier/harder>
```
---
## Review Checklist (For Critics and Self-Review)
- [ ] One `#` title at top; headings are unique and ordered.
- [ ] No broken links to repo files; link paths use `/`.
- [ ] Fenced code blocks are balanced; language tags are present where relevant.
- [ ] The doc is skimmable: short sections, short bullets, minimal redundancy.
- [ ] No secrets, tokens, or sensitive logs embedded.
- [ ] Changes are minimal and do not rewrite unrelated sections.
---
## Standard Checks (Optional, Recommended)
Use these when you want a repeatable “doc QA” pass. If the repo does not have these tools configured, treat this section as guidance (do a manual check instead).
- **Markdown lint**: catch common Markdown style issues (headings, fences, spacing).
- **Spell check**: catch typos and inconsistent terminology (especially in headings).
- **Link check**: validate external URLs (best-effort) and internal relative links.
Suggested tooling (choose one set; do not require all):
- `markdownlint-cli2` (Markdown lint)
- `cspell` (spell check)
- `lychee` (link check)
Minimum manual equivalent if you cannot run tools:
- Re-scan headings: one `#`, no skipped levels, no duplicates.
- Re-scan all new/edited links: open targets; fix path separators and casing.
- Re-scan code fences: ensure opening/closing fences match; add language tags.
---
## References
- Agent file and repo context standards: `framework/spec/appendices/01-appendix-a1-ai-and-llm-standards.md` (A1.1)
- VS Code Copilot customization overview: https://code.visualstudio.com/docs/copilot/customization/overview
---
> Source: [AlexandrSurkov/ForgentFramework](https://github.com/AlexandrSurkov/ForgentFramework) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Sections and files
Listed in source order.
sections -> When to Load This Skill → Requirements (Must-Haves) → R1 — Language and permanence → R2 — Document structure → R3 — Links → R4 — Anchors
terms -> English · relative links · Markdown lint · Spell check · Link check
files/cmd -> .md · *.md · .github/decisions/ · AGENTS.md · llms.txt · copilot-instructions.md · .agent.md · # ...
body sha256 -> 9a27b0a37bff
When to Load This Skill
Load this skill when you: Create or edit any
*.mdfile Write documentation changes (README, guides, design docs) Create or update ADRs in.github/decisions/Maintain repo context files such asAGENTS.md,llms.txt, orcopilot-instructions.mdRequirements (Must-Haves)
Agents writing or editing Markdown in this repo must satisfy all of the following:
R1 — Language and permanence
All committed Markdown must be English. Avoid time-sensitive phrasing (“today/now”) unless a date is explicitly stated.
R2 — Document structure
Exactly one top-level title: a single
# ...heading. Headings are hierarchical and ordered:#→##→###(no skipped levels). Headings are unique (avoid duplicates that may break anchors).R3 — Links
Prefer relative links for repo files. Do not introduce broken links; if you add/change a link, verify the target exists in the workspace. Use
/as a path separator (never\). Use descriptive link text (avoid dumping raw URLs unless the URL itself is the reference).