Agent skill

document-formatting

Apply standard document formatting, metadata headers, and markdown structure when creating or updating project documents. Use when writing any document in the knowledge base.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/document-formatting

SKILL.md

Document Formatting Standards

Apply these standards when creating or modifying any document in the project.

YAML Frontmatter

Every document MUST have YAML frontmatter at the top:

Intake Documents (to-process/)

yaml
---
source: zoom|slack|jira|confluence|email|meeting|notes
original_filename: original-name.txt
intake_date: 2024-01-15
document_date: 2024-01-15
status: pending
participants:
  - Name One
  - Name Two
tags: []
source_confidence: high|medium|low
---

Processed Documents (processed/)

yaml
---
source: zoom|slack|jira|confluence|email|meeting|notes
original_filename: original-name.txt
intake_date: 2024-01-15
document_date: 2024-01-15
processed_date: 2024-01-15
status: processed
participants:
  - Name One
  - Name Two
tags:
  - topic1
  - topic2
extracted:
  tasks: 5
  definitions: 2
  people: 3
related_documents:
  - path/to/related.md
---

Knowledge Base Entries

yaml
---
type: task|definition|wiki|person|status|jira-draft
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
tags:
  - tag1
  - tag2
---

Document Structure by Type

Task Entry

markdown
---
type: task
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
---

# Task: Brief Title

**Assignee:** Name or Unassigned
**Deadline:** YYYY-MM-DD or Not specified
**Priority:** High | Medium | Low | Not specified
**Status:** Pending | In Progress | Blocked | Done
**Project:** Project name

## Description

Clear description of what needs to be done.

## Source Context

> Original quote from source document

## Dependencies

- Depends on: [other task or item]
- Blocks: [what this blocks]

## Notes

Additional context or updates.

Definition Entry

markdown
---
type: definition
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
---

# Term Name

**Also known as:** Alias1, Alias2 (if any)

## Definition

Clear, concise definition of the term.

## Context

How this term is used in the project context.

## Related Terms

- [[related-term-1]]
- [[related-term-2]]

## Sources

- First mentioned: [source document]
- Also appears in: [other documents]

Person Profile

markdown
---
type: person
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
---

# Full Name

## Basic Info

| Field | Value |
|-------|-------|
| Role | Job Title |
| Team | Team Name |
| Expertise | Area1, Area2 |

## Responsibilities

- Responsibility 1
- Responsibility 2

## Document Mentions

| Date | Document | Context |
|------|----------|---------|
| 2024-01-15 | source.md | Brief context |

## Working Relationships

- Works with: Name1, Name2
- Reports to: Manager Name

Project Status

markdown
---
type: status
project: project-name
period: 2024-W03 or 2024-01-15
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
---

# Project Name - Status Update

**Period:** Week of January 15, 2024
**Updated:** 2024-01-15

## Summary

Brief summary of current state.

## Progress

- Completed item 1
- Completed item 2

## In Progress

- Current work item 1
- Current work item 2

## Blockers

- Blocker 1
- Blocker 2

## Decisions Made

- Decision 1: Rationale
- Decision 2: Rationale

## Next Steps

- Upcoming item 1
- Upcoming item 2

JIRA Draft

markdown
---
type: jira-draft
created: 2024-01-15
source_document: processed/2024-01-15-zoom-sprint.md
suggested_project: PROJ
---

# [Draft] Ticket Title

**Type:** Story | Bug | Task | Epic
**Priority:** High | Medium | Low
**Suggested Assignee:** Name or Unassigned

## Summary

One-line summary for JIRA title.

## Description

Detailed description of the work.

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Source Context

> Original discussion that led to this ticket

**From:** [source document]

## Notes

Any additional context for ticket creation.

Wiki Article

markdown
---
type: wiki
created: 2024-01-15
updated: 2024-01-15
sources:
  - processed/2024-01-15-zoom-sprint.md
tags:
  - topic1
  - topic2
---

# Article Title

## Overview

Brief overview of the topic.

## Details

### Section 1

Content for section 1.

### Section 2

Content for section 2.

## Related

- [[related-article-1]]
- [[related-article-2]]

## Sources

- [Source Document](path/to/source.md)

Proposed Update

markdown
---
type: proposed-update
proposal_id: update-001
created: 2024-01-15
target_file: knowledge/tasks/project-tasks.md
change_type: update|add|merge|archive
source_document: processed/2024-01-15-zoom-sprint.md
confidence: high|medium|low
status: pending_review
---

# Proposed Update: Brief Title

## Target

**File:** knowledge/tasks/project-tasks.md
**Section:** Task status for "Implement auth"

## Change Type

`update` - Modify existing content

## Current Content

```markdown
**Status:** In Progress

Proposed Content

markdown
**Status:** Done
**Completed:** 2024-01-15

Rationale

In the sprint review meeting, John confirmed this task was completed.

Source Evidence

Document: processed/2024-01-15-zoom-sprint.md Quote:

"The authentication work is done, we merged it yesterday."


Review Actions

  • Approve and apply
  • Modify and apply
  • Reject
  • Defer

Reviewer Notes:


## Naming Conventions

### File Names

- **Dates**: Always `YYYY-MM-DD` format
- **Sources**: Lowercase (`zoom`, `slack`, `jira`, `confluence`, `email`, `meeting`, `notes`)
- **Descriptions**: Lowercase, hyphens for spaces, max 50 characters
- **Full pattern**: `YYYY-MM-DD-<source>-<description>.md`

### Examples

2024-01-15-zoom-sprint-planning.md 2024-01-16-slack-data-pipeline-discussion.md 2024-01-17-jira-proj-1234-auth-bug.md 2024-01-18-email-quarterly-review.md 2024-01-19-meeting-architecture-review.md 2024-01-20-notes-research-findings.md


### Knowledge Base Files

- **Tasks**: `<project>-tasks.md` or `<topic>-tasks.md`
- **Definitions**: `<term>.md` (lowercase, hyphens)
- **People**: `<firstname>-<lastname>.md` (lowercase)
- **Wiki**: `<topic>.md` (descriptive name)
- **Status**: `<project>-status.md` or `<project>-YYYY-MM-DD.md`
- **JIRA drafts**: `draft-<brief-title>.md`

## Markdown Guidelines

1. **Headers**: Use `#` hierarchy (H1 for title, H2 for sections, etc.)
2. **Lists**: Use `-` for unordered, `1.` for ordered
3. **Code**: Use backticks for inline, triple backticks for blocks
4. **Links**: Use `[[internal-link]]` or `[text](path)` format
5. **Tables**: Use standard markdown table syntax
6. **Quotes**: Use `>` for quoted text from sources
7. **Checkboxes**: Use `- [ ]` for incomplete, `- [x]` for complete

Didn't find tool you were looking for?

Be as detailed as possible for better results