agentleFS
develeepdeveleep/dev-gongbang/skills/productivity/write-docs/SKILL.md

write-docs

Skill1 starsChanged 19 days agoMITView on GitHub

분야·독자·목적·톤·자료를 질문으로 정한 뒤 글 초안을 쓰거나, 가져온 초안과 기존 문서를 고친다. 기술 문서는 토스 테크니컬 라이팅 가이드의 문서 유형과 원칙을 따른다.

45 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use close-spec, design-with-images and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • dzhngSkill

    close-spec

    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).

    Also in 5 projects that use this

  • dzhngSkill

    design-with-images

    Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.

    Also in 5 projects that use this

  • transitive-bullshitSkill

    compare-screenshots

    Compare screenshots against the intended design, distinguishing approved references from historical baselines. Use for iterative implementation matching, before/after visual review, objective image telemetry, or checking a lone capture for flat, empty, or badly framed content.

    Also in 5 projects that use this

  • LucasMatuszewskiSkill

    audit-agents

    Audit and maintain agent configuration files (.claude/agents, AGENTS.md, CLAUDE.md, agent-memory). Checks for duplicates, outdated info, naming conflicts, wrong technical facts, and files over 200 lines. Fixes all issues and commits.

    Also in 5 projects that use this

  • wolverin0Skill

    audit-decisions

    Standardize remediation decisions, baseline-policy entries, and legal-review banners for accepted, deferred, or policy-blocked audit findings.

    Also in 4 projects that use this

  • rhnfzlSkill

    explore-unknowns

    Walk the user through mapping the unknowns of a task before, during, and after they build it, and hand them a four-quadrant map (settled ground, open decisions, taste, and landmines) they keep. Reach for this eagerly whenever a request is ambiguous or underspecified, the codebase or domain is unfamiliar, the user will "know it when they see it", a reference implementation must be understood before porting, a build-queue or architecture-changing task is about to start, a mid-build deviation needs capturing, or a finished change needs buy-in or verified understanding before merge. Trigger even when the skill is not named: "do a blindspot pass", "find my unknown unknowns", "interview me about this change", "brainstorm the approach for a task I am about to build", "help me scope this", "what am I missing here", "plan this before I build", "I know nothing about X in this codebase". When a territory profile is present it reads memory and the graph first and feeds the map into the build pipeline; without one it degrades to a plain general map. Not for trivial or mechanical tasks with clear acceptance criteria, single-fact lookups, pure debugging of a known symptom, or pure code review, those have their own tools. Do not use it to run the build itself; the map is the deliverable and implementation remains a separate task, whether it has not started or is already underway.

    Also in 5 projects that use this

  • +5 more from dzhng

The file

Files
SKILL.md

Write Docs

새 글 초안 작성, 가져온 초안 다듬기, 기존 문서 수정을 맡는다. 쓰기 전에 분야, 독자, 목적, 톤, 자료를 정하고 분야에 맞는 원칙으로 쓴다. 결과를 보여 준 뒤에는 사용자의 피드백에 따라 고치기를 반복한다.

어느 분야에서나 가장 앞서는 원칙은 사실, 수치, 경로, 이름, 근거를 지어내지 않는 것이다. 다른 원칙과 부딪치면 이 원칙을 따른다.

작업 흐름

1. 요청 파악

요청, 가져온 초안, 수정할 파일에서 다음 항목을 찾는다.

  • 분야: 대화, 조언, 이야기, 의견, 설명, 기술 문서 중 하나. 기술 문서면 유형(학습, 문제 해결, 참조, 설명)까지 정한다.
  • 독자: 누가 읽는가
  • 목적: 이 글로 무엇을 이루려 하는가
  • 톤
  • 자료: 글에 담을 사실, 코드, 문서, 링크
  • 수정 범위: 초안 다듬기나 문서 수정일 때만. 문장만 고칠지, 구조까지 바꿀지

원본과 자료는 받은 방식대로 읽는다. 첨부나 경로로 받은 파일은 그대로 읽고, SharePoint·OneDrive 같은 링크는 그 링크를 읽을 수 있는 커넥터나 MCP 도구로 읽는다. 읽지 못하면 쓰기를 시작하지 않고, 파일을 직접 붙여 넣거나 그 링크를 읽을 커넥터를 연결하라고 안내한다.

수정 작업이면 원본을 끝까지 읽는다. 이미 분명한 항목은 묻지 않고 한 줄로 되짚는다. 예: 확인됨: 독자 - 사내 백엔드 개발자 (요청에 있음)

2. 빈 항목 질문

비어 있거나 해석이 둘 이상인 항목만 묻는다.

  • 사용자에게 선택지로 묻는다. 선택지를 보여 주는 질문 도구가 있으면 그것으로, 없으면 번호 목록으로 묻고 답을 기다린다. 선택지에 없는 답은 기타(직접 입력)로 받는다. 분야는 "기술 문서 / 설명 / 의견 / 대화·조언·이야기"로 묻고, 기술 문서를 고르면 유형 4개를 이어서 묻는다. 수정 범위는 "문장만 / 구조까지"로 묻는다.
  • 자료처럼 길게 답해야 하는 항목은 선택 질문의 답을 받은 뒤 따로 묻는다. 자료 요청을 그 턴의 마지막 메시지로 보내고 사용자의 답을 기다린다. 선택창과 같은 메시지에 넣거나 도구 호출 사이에 쓰면 사용자가 텍스트 질문을 보지 못하거나 건너뛰기 쉽다.

3. 원칙 읽기

  • 모든 분야: reference/clear-writing.md를 읽는다.
  • 기술 문서: reference/tech-writing.md도 읽는다. 새 초안이거나 수정 범위가 "구조까지"면 고른 유형의 권장 구조를 글의 뼈대로 쓴다. 수정 범위가 "문장만"이면 원본 구조를 그대로 둔다.

두 원칙이 부딪치면 분야로 정한다. 기술 문서는 tech-writing.md를 따르고(예: 한 문장에는 생각 하나만 담고 짧게 쓴다), 나머지 다섯 분야는 clear-writing.md를 따른다(예: 조건과 이유는 주장에 붙여 두고 잘게 끊지 않는다). 지어내지 않는다는 원칙은 분야와 상관없이 앞선다.

4. 쓰기

  • 새 초안: 받은 자료로만 쓴다. 구체적으로 쓰라는 원칙도 자료에 있는 사실로만 지킨다.
  • 초안 다듬기, 문서 수정: 사실의 의미와 글쓴이의 목소리를 지킨다. 수정 범위가 "문장만"이면 섹션 순서와 제목을 바꾸지 않는다.

자료에 없는 사실이 필요하면, 답에 영향이 클 때는 묻는다. 이 질문도 2단계의 자료 요청처럼 그 턴의 마지막 메시지로 보내고, 답을 받은 뒤 쓰기를 이어 간다. 아니면 그 자리에 [확인 필요: 타임아웃 기본값]처럼 무엇이 빠졌는지 보이는 표시를 남긴다. 그럴듯한 값을 넣거나 "가능성이 있다" 같은 모호한 문장으로 덮지 않는다.

5. 검토

결과를 내기 전에 "주의할 점" 목록의 패턴을 찾아 고친다. 기술 문서면 다음도 확인한다.

  • 제목 바로 아래에 개요가 있는가
  • 같은 개념을 같은 용어로 쓰고, 영문 용어와 한글 용어를 섞지 않았는가
  • 약어를 처음 쓸 때 전체 이름을 풀어 적었는가
  • "다음으로", "앞서 설명했듯이" 같은 메타 담화가 남아 있는가
  • "~을 통해", "~을 수행합니다" 같은 번역체가 남아 있는가

고칠 때 근거 없는 내용이나 불필요한 설명을 더하지 않는다. 검토했다고 알리거나 문체 보고서를 붙이지 않는다.

6. 전달

결과를 채팅에 보여 준다. 기존 파일을 고친 경우에도 수정본을 채팅에 먼저 보여 주고, 사용자가 승인하면 파일에 반영한다. [확인 필요] 표시가 있으면 결과 아래에 그 목록을 한 줄씩 적어 사용자가 채울 수 있게 한다.

7. 수정 반복

사용자가 고칠 점을 말하면 4~6단계를 다시 한다. 분야가 바뀌면 3단계에서 원칙부터 다시 고른다.

주의할 점

이 작업에서 자주 나오는 패턴이다. 쓸 때 피하고, 5단계 검토에서 다시 찾는다.

  • 독자가 꺼낸 적 없는 대안을 부정하고 요점을 밝히는 틀: "X가 아니라 Y다", "문제는 X가 아니다", "X는 덜, Y는 더"
  • 모호한 글을 구체적으로 만들려고 사건, 동기, 감정, 수량, 근거를 지어내기. 기술 문서의 수치, 경로, 버전, 브라우저명도 같다
  • 독자가 대상을 찾을 수 없는 "이것", "이 패턴", "그 경계" 같은 지시어
  • 결론에 필요한 원인, 조건, 중간 단계를 빼서 독자가 논리 연결을 스스로 채워야 하는 곳
  • 독자가 해독해야 하는 은유, 실제 대상보다 먼저 나오는 이미지
  • 작은 사실마다 문장을 끊어 결정타처럼 늘어놓는 리듬
  • 짧게 쓰려고 명사를 줄줄이 잇거나 조사와 연결어를 빼서 압축한 문장: "세션 토큰 만료 갱신 로직"

참조 파일

  • reference/clear-writing.md: 3단계에서 모든 분야에 읽는다. 처음 읽을 때 생각을 따라올 수 있게 쓰는 원칙 7개, 지킬 것, 대비 예시가 있다.
  • reference/tech-writing.md: 3단계에서 분야가 기술 문서일 때 읽는다. 문서 유형 4개와 권장 구조, 정보 구조 원칙 6개, 문장 원칙 5개가 있다.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.