Update Content Skill

Generic file update Skill that respects RULE.md constraints and maintains format consistency.

When to use this Skill

• User says "update", "edit", "modify", "change"

• User references existing file or content

• User requests content revision

• User mentions specific file to update

Workflow

1. Identify Target File

If user provides file path:

• Verify file exists

• Confirm with user if ambiguous

If user provides topic/title only:

• Search for file using Grep or Glob

• Pattern: **/keyword.md

• If multiple matches: present list, ask user to choose

• If no matches: report not found, offer to create instead

Search strategies:

• Filename match: find . -name "keyword"

• Content match: grep -r "keyword" .

• README.md index: Search README.md files for references

2. Read Current Content

Load existing file:

• Use Read tool to load full content

• Understand current structure:

• Frontmatter (if present)

• Section headings

• Content organization

• Formatting style

Analyze format:

• Identify markdown structure

• Note any special formatting

• Detect metadata or frontmatter

• Understand content layout

3. Read Directory RULE.md

Locate and read RULE.md:

• Check file's directory for RULE.md

• If not found, check parent directories (inheritance)

• Parse RULE.md for update rules

Check for:

• Are updates allowed? (some directories may be append-only or immutable)

• Format requirements to maintain

• Required fields that must be preserved

• Update workflow (e.g., "always add changelog entry")

• Versioning requirements

Example RULE.md update rules:

Update Rules

• Preserve frontmatter fields: title, date, tags
• Add "Last updated" timestamp to frontmatter
• Append changes to "Changelog" section
• Maintain markdown heading structure

4. Execute Update

Apply requested changes:

• Use Edit tool for targeted changes

• Or Write tool for complete rewrites (if needed)

• Maintain existing format per RULE.md

• Preserve required fields/structure

Update modification metadata:

• Update "Last updated" field (if present)

• Update modification timestamp in frontmatter

• Add changelog entry (if RULE.md requires)

• Preserve original creation date

Maintain consistency:

• Keep same formatting style (indentation, line breaks, etc.)

• Preserve markdown structure (headings hierarchy)

• Maintain frontmatter format (if present)

• Keep cross-references valid

5. Governance Update

Update README.md:

• Read current README.md

• Find entry for this file

• Update description if content changed significantly

• Update "Last modified" timestamp

• Add to "Recent Changes" section

• Save README.md

Update parent README.md if needed:

• If file significance changed

• If file moved to different category

Verify updates:

• Check README.md is valid markdown

• Ensure timestamps are current

• Verify file is still listed correctly

6. Report to User

Confirm update complete:

✅ File updated successfully

File: [path to file] Changes: [summary of changes made] Format: [maintained per RULE.md]

README.md updated:

• [directory]/README.md

What changed: [Brief description of modifications]

Special Cases

Frontmatter Updates

If file has YAML frontmatter:

title: Original Title date: 2025-10-20 updated: 2025-10-28 # ← Update this tags: [ai, ml]

[Content]

Update process:

• Parse frontmatter

• Preserve required fields (per RULE.md)

• Update modification fields

• Update content

• Regenerate frontmatter with updates

Versioned Content

If RULE.md requires versioning:

Changelog

v1.2.0 (2025-10-28)

• [Changes made]

v1.1.0 (2025-10-25)

• [Previous changes]

Update process:

• Read current version

• Increment version number (per RULE.md versioning scheme)

• Add changelog entry

• Update content

• Update version in frontmatter

Structured Content

If content has specific structure (sections, tables, etc.):

Preserve structure:

• Identify section to modify

• Update only targeted section

• Maintain heading hierarchy

• Keep other sections unchanged

• Ensure valid markdown

Append-Only Updates

If RULE.md specifies append-only (like logs):

RULE.md says: "This directory is append-only"

Update process:

• Read current content

• Append new content at end

• Don't modify existing content

• Add timestamp for new entry

• Update README.md

Cross-Reference Updates

If file contains links to other files:

After update:

• Verify cross-references still valid

• If file renamed/moved: update references

• Check both directions (incoming and outgoing links)

• Report any broken links

Error Handling

File Not Found

User: "Update the transformer note" → Search for file with "transformer" keyword → No matches found → Ask: "I couldn't find a file about transformers. Would you like to create one instead?"

Multiple Matches

User: "Update the transformer note" → Find 3 files with "transformer":

1. Research/AI/2025-10-28-transformer-architecture.md
2. Research/AI/2025-10-20-transformer-applications.md
3. Work/Projects/transformer-project.md → Present list: "I found 3 files. Which one?" → User selects → Proceed

RULE.md Forbids Updates

RULE.md says: "This directory is immutable" → Warn user: "RULE.md indicates this directory should not be modified" → Ask: "Do you want to proceed anyway (override rule)?" → If yes: update and note rule override in README.md → If no: cancel operation

Format Unclear

Current file has unusual format → Ask user: "This file has custom formatting. Should I:

1. Maintain exact current format
2. Apply standard format per RULE.md
3. Let you specify format"

Conflicting Changes

File was modified since user last viewed → Warn: "This file was modified recently (timestamp)" → Show recent changes → Ask: "Proceed with update or review changes first?"

Update Breaks Structure

Proposed update would break markdown structure or frontmatter → Warn: "This update would create invalid structure" → Suggest: "I can apply a modified version that maintains structure" → Ask for confirmation

Integration with Governance

This Skill automatically invokes the governance protocol:

Before update:

• Locate and read RULE.md

• Validate update is allowed

• Check format requirements

During update:

• Maintain format per RULE.md

• Preserve required fields

• Follow update workflows

After update:

• Update README.md

• Update modification timestamps

• Verify structure maintained

Examples

Example 1: Simple Update

User: "Update the transformer architecture note with new information about attention mechanisms"

Skill workflow:

• Searches for file → Finds Research/AI/2025-10-28-transformer-architecture.md

• Reads current content

• Reads Research/AI/RULE.md → Updates allowed, maintain frontmatter

• Applies changes using Edit tool

• Updates "updated" field in frontmatter to 2025-10-28

• Updates Research/AI/README.md timestamp

• Reports: "✅ Updated transformer-architecture.md with attention mechanisms section"

Example 2: Append-Only Log

User: "Add today's entry to my worklog"

Skill workflow:

• Finds Work/WorkLog/2025/Q4/10-October/2025-10-28.md

• Reads current content

• Reads Work/WorkLog/RULE.md → Append-only, add timestamp

• Appends new entry at end with timestamp

• Updates hierarchical README.md files

• Reports: "✅ Added entry to today's worklog"

Example 3: Versioned Document

User: "Update the project spec with new requirements"

Skill workflow:

• Finds Work/Projects/project-spec.md

• Reads current version → v1.1.0

• Reads Work/Projects/RULE.md → Requires versioning and changelog

• Increments version → v1.2.0

• Adds changelog entry:

v1.2.0 (2025-10-28)

• Added new requirements section

• Updates content

• Updates frontmatter version field

• Updates README.md

• Reports: "✅ Updated project-spec.md to v1.2.0"

Best Practices

• Always preserve existing structure - Don't reformat unless requested

• Read RULE.md first - Understand update constraints

• Use Edit for precision - Target specific changes, don't rewrite entire file

• Maintain metadata - Update timestamps, versions, changelog

• Update README.md immediately - Keep index current

• Verify cross-references - Ensure links still work

• Report clearly - User should know what changed

• Handle conflicts gracefully - Warn about concurrent modifications

Notes

• This Skill works with any file structure by reading RULE.md

• Preserves format by default, changes only what's requested

• Respects update rules defined in RULE.md

• Automatically maintains README.md index

• Works in parallel with CLAUDE.md subagents

• Never updates RULE.md itself (that requires explicit permission via governance agent)