{"id":"8db15a64-0c47-4883-a35d-4d8b0ae21a38","shortId":"MF6Yxq","kind":"skill","title":"docmap","tagline":"Conventions for writing, organizing, and browsing documentation in a docs/ directory using docmap. Use when creating documents, restructuring documentation, or unsure about frontmatter format and file naming conventions.","description":"# Authoring Documentation\n\nAll project documentation lives in the `docs/` directory. The `docmap` CLI lets both humans and AI agents discover and read documents without leaving the terminal.\n\n## Browsing with CLI\n\n> Run commands via the project's package manager (e.g. `npm run docmap --`, `pnpm docmap`).\n\n```bash\ndocmap                                          # list root docs\ndocmap --dir topic-a --dir topic-b/sub-topic-c  # list subdirectories\ndocmap --recursive                              # list everything\ndocmap --read doc-1.md --read topic-a/doc-2.md  # read documents (frontmatter stripped)\ndocmap --check                                  # validate all files\n```\n\n## Workflow\n\n1. **Understand the Subject** — clarify what needs to be documented. Ask the user if unclear.\n2. **Determine Placement** — scan existing docs (`docmap --recursive`). Decide: new file, existing file, which subdirectory. Discuss with the user if unclear.\n3. **Write** — follow the conventions below.\n\n## Writing Guidelines\n\n- **Target audience:** an experienced newcomer — someone technically capable but unfamiliar with this specific project.\n- Be brief and specific — no obvious information, no generic best practices.\n- Typical document: 40–80 lines.\n- Prefer referencing source files over large code blocks.\n- If the title makes the purpose obvious, omit the `summary`.\n\n## File and Directory Naming\n\n- Use **lowercase-with-dashes** (kebab-case) for new files and directories.\n- Uppercase is allowed by the CLI (e.g. `RELEASING.md`).\n- Names must be **shell-safe**: no spaces, no quotes, no special characters. The CLI validates this for both files and directories. Use `docmap --check` to verify.\n- Use `.md` (Markdown) for all documents.\n- Use short, descriptive names.\n- Group related documents into subdirectories. Subdirectories can be nested.\n\n## YAML Frontmatter\n\n`.md` files can start with a YAML frontmatter block. Add it when it adds value — especially when the filename or heading alone is not explicit enough. It is not required; when frontmatter is absent, the CLI falls back to the first `# heading` in the document body for the title. Fields:\n\n| Field | Required | Description |\n| --- | --- | --- |\n| `title` | No | A human-readable display name shown in listings. Falls back to the first `# heading` when absent. |\n| `summary` | No | One concise sentence. If the title already makes the purpose obvious, omit the summary to avoid redundancy. |\n| `read_when` | No | A YAML list of short, action-oriented hints. Each hint completes: *\"Read this document when you are…\"* |\n\n## Document Body\n\nAfter the closing `---` of the frontmatter, write standard Markdown. There are no constraints on the body format — use headings, code blocks, tables, and lists as needed.\n\n```markdown\n---\ntitle: Your Title Here\nsummary: A one-sentence description of what this document covers.\nread_when:\n  - first situation when this document is useful\n  - second situation\n---\n\n# Your Title Here\n\nStart your content here…\n```\n\n## References\n\n- [Installing Docmap CLI](references/installation.md) — how to add docmap CLI to a project.\n- [Bootstrapping Documentation](references/bootstrapping-documentation.md) — instructions for creating or extending project documentation by exploring the codebase.\n- [Migrate Existing Documents](references/migrate-existing-docs.md) — guide for bringing an existing folder of Markdown documents into docmap conventions (naming, frontmatter).\n- [Migrate Skills to Docmap Documentation](references/migrate-skills-to-docmap.md) — guide for moving internal project documentation from agent skills into `docs/`.","tags":["docmap","alignfirst","paleo","agent-skills","agentic-coding","agentic-engineering"],"capabilities":["skill","source-paleo","skill-docmap","topic-agent-skills","topic-agentic-coding","topic-agentic-engineering"],"categories":["alignfirst"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/paleo/alignfirst/docmap","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add paleo/alignfirst","source_repo":"https://github.com/paleo/alignfirst","install_from":"skills.sh"}},"qualityScore":"0.489","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 79 github stars · SKILL.md body (3,623 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:56:46.454Z","embedding":null,"createdAt":"2026-05-10T18:56:14.558Z","updatedAt":"2026-05-18T18:56:46.454Z","lastSeenAt":"2026-05-18T18:56:46.454Z","tsv":"'/doc-2.md':102 '/sub-topic-c':88 '1':113 '2':128 '3':149 '40':184 '80':185 'absent':311,349 'action':378 'action-ori':377 'add':287,291,459 'agent':48,510 'ai':47 'allow':224 'alon':299 'alreadi':358 'ask':123 'audienc':158 'author':30 'avoid':367 'b':87 'back':315,343 'bash':74 'best':180 'block':194,286,412 'bodi':323,391,407 'bootstrap':465 'brief':172 'bring':485 'brows':7,57 'capabl':164 'case':216 'charact':242 'check':108,254 'clarifi':117 'cli':42,59,227,244,313,455,461 'close':394 'code':193,411 'codebas':478 'command':61 'complet':383 'concis':353 'constraint':404 'content':450 'convent':2,29,153,494 'cover':433 'creat':17,470 'dash':213 'decid':136 'descript':265,330,428 'determin':129 'dir':80,84 'directori':12,39,207,221,251 'discov':49 'discuss':143 'display':337 'doc':11,38,78,133,513 'doc-1.md':97 'docmap':1,14,41,71,73,75,79,91,95,107,134,253,454,460,493,500 'document':8,18,20,31,34,52,104,122,183,262,269,322,386,390,432,440,466,474,481,491,501,508 'e.g':68,228 'enough':303 'especi':293 'everyth':94 'exist':132,139,480,487 'experienc':160 'explicit':302 'explor':476 'extend':472 'fall':314,342 'field':327,328 'file':27,111,138,140,190,205,219,249,279 'filenam':296 'first':318,346,436 'folder':488 'follow':151 'format':25,408 'frontmatt':24,105,277,285,309,397,496 'generic':179 'group':267 'guid':483,503 'guidelin':156 'head':298,319,347,410 'hint':380,382 'human':45,335 'human-read':334 'inform':177 'instal':453 'instruct':468 'intern':506 'kebab':215 'kebab-cas':214 'larg':192 'leav':54 'let':43 'line':186 'list':76,89,93,341,374,415 'live':35 'lowercas':211 'lowercase-with-dash':210 'make':198,359 'manag':67 'markdown':259,400,418,490 'md':258,278 'migrat':479,497 'move':505 'must':231 'name':28,208,230,266,338,495 'need':119,417 'nest':275 'new':137,218 'newcom':161 'npm':69 'obvious':176,201,362 'omit':202,363 'one':352,426 'one-sent':425 'organ':5 'orient':379 'packag':66 'placement':130 'pnpm':72 'practic':181 'prefer':187 'project':33,64,170,464,473,507 'purpos':200,361 'quot':239 'read':51,96,98,103,369,384,434 'readabl':336 'recurs':92,135 'redund':368 'refer':452 'referenc':188 'references/bootstrapping-documentation.md':467 'references/installation.md':456 'references/migrate-existing-docs.md':482 'references/migrate-skills-to-docmap.md':502 'relat':268 'releasing.md':229 'requir':307,329 'restructur':19 'root':77 'run':60,70 'safe':235 'scan':131 'second':443 'sentenc':354,427 'shell':234 'shell-saf':233 'short':264,376 'shown':339 'situat':437,444 'skill':498,511 'skill-docmap' 'someon':162 'sourc':189 'source-paleo' 'space':237 'special':241 'specif':169,174 'standard':399 'start':281,448 'strip':106 'subdirectori':90,142,271,272 'subject':116 'summari':204,350,365,423 'tabl':413 'target':157 'technic':163 'termin':56 'titl':197,326,331,357,419,421,446 'topic':82,86,100 'topic-a':81,99 'topic-agent-skills' 'topic-agentic-coding' 'topic-agentic-engineering' 'topic-b':85 'typic':182 'unclear':127,148 'understand':114 'unfamiliar':166 'unsur':22 'uppercas':222 'use':13,15,209,252,257,263,409,442 'user':125,146 'valid':109,245 'valu':292 'verifi':256 'via':62 'without':53 'workflow':112 'write':4,150,155,398 'yaml':276,284,373","prices":[{"id":"f943d4c0-1296-4905-a1c2-89a0a80f6fdb","listingId":"8db15a64-0c47-4883-a35d-4d8b0ae21a38","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"paleo","category":"alignfirst","install_from":"skills.sh"},"createdAt":"2026-05-10T18:56:14.558Z"}],"sources":[{"listingId":"8db15a64-0c47-4883-a35d-4d8b0ae21a38","source":"github","sourceId":"paleo/alignfirst/docmap","sourceUrl":"https://github.com/paleo/alignfirst/tree/main/skills/docmap","isPrimary":false,"firstSeenAt":"2026-05-10T18:56:14.558Z","lastSeenAt":"2026-05-18T18:56:46.454Z"}],"details":{"listingId":"8db15a64-0c47-4883-a35d-4d8b0ae21a38","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"paleo","slug":"docmap","github":{"repo":"paleo/alignfirst","stars":79,"topics":["agent-skills","agentic-coding","agentic-engineering"],"license":"cc0-1.0","html_url":"https://github.com/paleo/alignfirst","pushed_at":"2026-05-17T16:54:16Z","description":"The skill of Spartan developers who love well-written code","skill_md_sha":"3669f13e26af6d6f1ac7b3a8f5c29c088a502f1f","skill_md_path":"skills/docmap/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/paleo/alignfirst/tree/main/skills/docmap"},"layout":"multi","source":"github","category":"alignfirst","frontmatter":{"name":"docmap","license":"CC0 1.0","description":"Conventions for writing, organizing, and browsing documentation in a docs/ directory using docmap. Use when creating documents, restructuring documentation, or unsure about frontmatter format and file naming conventions."},"skills_sh_url":"https://skills.sh/paleo/alignfirst/docmap"},"updatedAt":"2026-05-18T18:56:46.454Z"}}