Agentic Skills Pattern for Reproducible Workflows

Executive Summary

The agentic skills pattern provides a framework for transforming one-off, ad-hoc AI-assisted workflows into reproducible, discoverable capabilities. By packaging domain knowledge, instructions, templates, and executable tools together, skills enable general-purpose AI agents to automatically apply specialized expertise when relevant tasks arise.

This research examines the skills pattern through the lens of recent work: processing 61 Desktop inbox items and establishing Odin↔Boox document sync. Both workflows involved significant ad-hoc problem-solving that could be captured as reusable skills for future sessions.

Key Finding: Skills decompose workflows into four elements—decision points, deterministic operations, reference knowledge, and orchestration logic—making implicit expertise explicit and reusable.

Table of Contents

1. The Skills Pattern (General)
2. Anthropic's Implementation
3. Analysis: Recent Workflows
4. Skills Design for Reproducibility
5. Implementation Considerations
6. Next Steps

The Skills Pattern (General)

Core Concept

Progressive disclosure of specialized knowledge that enables general-purpose agents to handle domain-specific workflows without context window overload.

Universal Pattern Components

Regardless of implementation (Anthropic, custom, other platforms), the skills pattern consists of:

1. Metadata Layer

• Name: Unique identifier
• Description: What the skill does AND when to use it
• Triggers: Keywords/contexts that make the skill relevant

2. Instructions

• Step-by-step workflow guidance
• Decision trees for branching logic
• Best practices and conventions
• Error handling and troubleshooting

3. Supporting Resources

• Templates for common documents
• Reference materials (formats, conventions, paths)
• Example outputs
• Checklists and validation criteria

4. Executable Tools

• Scripts for deterministic operations
• Commands with proper arguments
• File operation helpers
• API integrations

Design Philosophy

Progressive Disclosure Information loads in layers:

1. Metadata (always available for selection)
2. Core instructions (loaded when skill activates)
3. Extended resources (loaded on-demand)

This mirrors reference manuals: table of contents → specific chapters → detailed appendices.

Unbounded Context Through Execution By pairing instructions with filesystem access and code execution, agents can work with arbitrarily large skill libraries. Code serves dual purposes:

• Executable tools (deterministic, efficient)
• Self-documenting specifications (readable by agents and humans)

Composability Skills should invoke other skills. A high-level skill like "inbox-processor" might call:

• "document-reviewer" for PDF generation
• "para-organizer" for filing decisions
• "todo-manager" for task creation

Empirical Iteration Build skills based on validated workflows, not speculative needs:

1. Perform task ad-hoc with agent
2. Identify repeatable patterns
3. Extract into skill
4. Refine through real usage

Anthropic's Implementation

Claude Code Skills System

Discovery Mechanism: Skills are "model-invoked" — Claude autonomously decides when to activate based on request and skill description. Uses LLM reasoning, not embeddings or pattern matching.

File Structure:

~/.claude/skills/skill-name/
├── SKILL.md (required)
├── supporting-docs.md (optional)
└── scripts/ (optional)

SKILL.md Format:

---
name: skill-name
description: What it does and when to use it (max 1024 chars)
allowed-tools: [optional tool restrictions]
---

# Skill instructions in markdown

Three Skill Locations:

1. Personal (~/.claude/skills/) - Available across all projects
2. Project (.claude/skills/) - Team-shared via git
3. Plugin - Bundled with installed plugins

Key Insights from Anthropic

"Write specific descriptions" Vague: "Helps with documents" Specific: "Extract text and tables from PDF files, fill forms, merge documents"

The description must include concrete trigger terms for reliable discovery.

"Keep skills focused" One capability per skill. Composition is better than combination.

"Test with teammates" Validate that skills activate as expected. Descriptions that work for you might not work for others.

Analysis: Recent Workflows

Workflow 1: Desktop Inbox Processing

What Happened: (2025-11-11 Journal)

61 files on Desktop → Markdown inventory → PDF conversion → Boox annotation → Parse annotations → Execute 59 filing decisions

Ad-hoc Steps:

1. Catalogued all 61 files manually
2. Created markdown inventory with custom structure
3. Looked up pandoc command for PDF conversion
4. Determined archive directory name (date prefix convention)
5. Waited for Boox annotations
6. Parsed handwritten annotations (D/C/A/K codes)
7. Executed filing decisions:
   • 13 deletions
   • 14+ captures to RESOURCES/AREAS
   • 16+ archives
   • 14 TODO creations with metadata

Challenges:

• Inventory structure had to be designed from scratch
• PDF conversion options needed research
• Archive naming convention had to be remembered
• TODO metadata format required lookup
• File operation logic was custom for each item type
• No validation that all files were processed

Time Investment: ~2 hours for processing alone

Workflow 2: Boox Sync Infrastructure Setup

What Happened: (2025-11-11 Journal)

Research sync options → Install Syncthing + Tailscale → Configure selective sync → Test bidirectional flow → Validate with real content

Ad-hoc Steps:

1. Researched Boox capabilities and limitations
2. Evaluated sync solutions (Google Drive vs Syncthing)
3. Articulated decision criteria on-the-fly
4. Installed software on both devices
5. Configured Syncthing folders and .stignore
6. Discovered circular dependency issue
7. Iterated to better architecture
8. Validated end-to-end workflow

Challenges:

• Research was manual web searches
• Decision criteria emerged during discussion
• Configuration steps learned through trial
• .stignore patterns had to be discovered
• Validation steps were improvised
• Troubleshooting was reactive

Time Investment: ~3 hours for setup and validation

Workflow 3: Markdown → PDF → Annotate Pattern

What Happened: (Used in both sessions)

Create markdown → Convert to PDF optimized for e-ink → Sync to Boox → Annotate → Sync back → Process annotations

Ad-hoc Steps:

1. Write markdown content
2. Remember/lookup pandoc command
3. Check if PDF synced (manual Syncthing check)
4. Wait for human annotation on Boox
5. Check if annotations synced back
6. Manually correlate annotations to content
7. Execute decisions based on annotations

Challenges:

• PDF conversion parameters for e-ink not documented
• Sync status checking was manual
• Annotation retrieval location had to be discovered
• Processing annotations required context switching

Time Investment: ~30 min per iteration

Skills Design for Reproducibility

Skill 1: inbox-processor

Purpose: Process files from Desktop or other inbox locations into PARA system

Description: "Process Desktop inbox files into PARA system. Creates categorized inventory, generates annotatable PDF for Boox review, parses human decisions (Delete/Capture/Archive/Keep), and executes filing operations. Use when: 'process Desktop', 'clean inbox', 'organize files', 'file system cleanup'."

Components:

Instructions

## Workflow Overview
1. Discover all files in inbox location (default: ~/Desktop)
2. Categorize files by type and content
3. Generate markdown inventory with categories
4. Convert inventory to PDF for Boox review
5. Sync PDF and wait for human annotation
6. Parse annotation decisions (D/C/A/K)
7. Execute filing operations
8. Report summary

## File Categorization
Group files into:
- Quick Notes
- Technical Documents
- TODO Items (by domain: finance, family, tech, etc.)
- Screenshots (by date ranges)
- Images & Documents
- Videos

## Annotation Semantics
- D = Delete (remove permanently)
- C = Capture (file to RESOURCES or AREAS)
- A = Archive (move to ARCHIVES with date prefix)
- K = Keep (leave on Desktop, user will handle)
- Todo: [text] = Create TODO item in appropriate location

## Archive Naming Convention
Use date prefix: YYYY-MM-DD--description
Example: 2025-11-11--desktop-inbox-items

## Validation
- Verify all files accounted for
- Confirm no orphaned files remain
- Check TODO metadata is complete
- Report files skipped or kept

Supporting Resources

• templates/inbox-inventory.md - Markdown template for inventory
• templates/annotation-guide.md - Visual guide for annotation semantics
• reference/para-decision-tree.md - Where to file different content types
• reference/todo-metadata-format.md - TODO.md format specification

Executable Scripts

• scripts/generate-inventory.sh - Creates categorized markdown inventory
• scripts/convert-to-pdf.sh - Pandoc with e-ink optimization
• scripts/parse-annotations.py - Extract decisions from annotated PDF
• scripts/execute-filing.sh - Perform file operations safely
• scripts/check-sync-status.sh - Verify Syncthing sync completion

Invocation Triggers

• "process Desktop"
• "clean up inbox"
• "organize Desktop files"
• "file system cleanup"
• "process inbox items"

Skill 2: document-reviewer

Purpose: Generate annotatable PDFs for Boox review with proper e-ink optimization

Description: "Create annotatable PDF documents optimized for 10.3" Boox e-ink display. Converts markdown to PDF with appropriate margins, font sizes, and page breaks. Handles sync to Boox and retrieval of annotations. Use when: 'create review document', 'make PDF for Boox', 'generate annotatable', 'review on Boox'."

Components:

Instructions

## Workflow Overview
1. Accept markdown input (file or generated content)
2. Validate markdown formatting
3. Convert to PDF with e-ink optimizations
4. Save to synced location
5. Monitor sync status
6. Wait for annotations
7. Retrieve annotated version
8. Parse annotations if requested

## E-ink Optimization Parameters
- Page size: A4 or Letter
- Margins: 0.75 inch (easier touch targets)
- Font: 12pt serif (readable on e-ink)
- Line spacing: 1.5 (reduces eye strain)
- Page breaks: Preserve section boundaries
- Grayscale: True (e-ink native)

## Pandoc Command Template
pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V geometry:margin=0.75in \
  -V fontsize=12pt \
  -V linestretch=1.5 \
  -V colorlinks=false

## Sync Locations
- Output: ~/Documents/JOURNALS/ or ~/Documents/PROJECTS/
- These are synced to Boox automatically
- Annotations sync back from Boox to ~/Desktop/boox-notes/

## Validation
- PDF generated successfully
- File appears in Syncthing
- Sync completes (check timestamp)
- PDF is readable (spot check)

Supporting Resources

• templates/review-document.md - Template for structured reviews
• reference/pandoc-options.md - Full pandoc parameter reference
• reference/boox-specs.md - Boox NoteAir 3C display specifications

Executable Scripts

• scripts/md-to-boox-pdf.sh - Pandoc conversion with presets
• scripts/check-boox-sync.sh - Verify file synced to Boox
• scripts/wait-for-annotations.sh - Poll for annotated version
• scripts/extract-annotations.py - Parse annotation layer

Invocation Triggers

• "create review document"
• "make PDF for Boox"
• "generate annotatable"
• "convert to e-ink PDF"
• "review on Boox"

Skill 3: para-organizer

Purpose: File items into appropriate PARA locations based on actionability

Description: "Organize files and information into PARA structure (Projects/Areas/Resources/Archives) based on actionability and lifecycle. Applies naming conventions, creates metadata files, and maintains structure. Use when: 'file to PARA', 'organize into system', 'where does this belong', 'create project', 'create area'."

Components:

Instructions

## PARA Decision Tree

### Is it actionable with a specific outcome?
YES → PROJECTS/ (short-term effort with goal)
NO → Continue...

### Does it require ongoing maintenance?
YES → AREAS/ (long-term responsibility)
NO → Continue...

### Is it reference material for potential future use?
YES → RESOURCES/ (topic of interest)
NO → Continue...

### Is it completed, cancelled, or inactive?
YES → ARCHIVES/ (with date prefix)

## Naming Conventions

### Archive Naming
Format: YYYY-MM-DD--description
- Use date of archival (today)
- Use kebab-case for description
- Example: 2025-11-11--desktop-inbox-items

### Directory Naming
- Use kebab-case: property-management
- Nest related items: property/965-dills-bluff/
- Avoid delimiter-based: NOT property--965-dills-bluff

## Metadata Files

### PROJECT.md
Required frontmatter:
- name: Project name
- status: planning|active|paused|blocked|completed|cancelled
- created: YYYY-MM-DD
- updated: YYYY-MM-DD
- goal: One sentence objective

### AREA.md
Required frontmatter:
- name: Area name
- created: YYYY-MM-DD
- updated: YYYY-MM-DD
- description: What this area encompasses

### TODO.md
Present in root, PROJECTS/*, and AREAS/*
Uses checkbox semantics and inline metadata

## Validation
- Metadata file created if needed
- Directory structure follows conventions
- No orphaned files
- Archive dates are accurate

Supporting Resources

• templates/PROJECT.md - Project metadata template
• templates/AREA.md - Area metadata template
• templates/TODO.md - TODO file template
• reference/para-examples.md - Real examples of PARA organization
• reference/actionability-guide.md - When to choose each category

Executable Scripts

• scripts/create-project.sh - Initialize new project with metadata
• scripts/create-area.sh - Initialize new area with metadata
• scripts/archive-with-date.sh - Move to archives with date prefix
• scripts/validate-structure.sh - Check PARA conventions

Invocation Triggers

• "file to PARA"
• "organize into system"
• "where does this belong"
• "create project"
• "create area"
• "archive this"

Skill 4: boox-sync-manager

Purpose: Manage Syncthing + Tailscale sync configuration for Boox device

Description: "Manage and troubleshoot Syncthing + Tailscale sync between Odin and Boox NoteAir 3C. Check sync status, add folders, modify .stignore patterns, diagnose issues. Use when: 'sync not working', 'check sync status', 'add folder to Boox', 'modify sync', 'Boox connection issues'."

Components:

Instructions

## Architecture Overview
- Odin: Mac Studio (always-on sync hub)
- Boox: NoteAir 3C e-ink device
- Connection: Syncthing over Tailscale VPN
- Primary folder: ~/Documents (selective sync via .stignore)
- Secondary folder: ~/Desktop/boox-notes (Boox → Odin only)

## Device IDs
- Odin Syncthing: JFUO2AF
- Boox Syncthing: RZUAPPR
- Odin Tailscale: JFUO2AF

## Common Operations

### Check Sync Status
1. Open http://localhost:8384 (Syncthing Web UI)
2. Verify "Documents" folder shows "Up to Date"
3. Check "Recent Changes" for latest sync
4. Verify Boox device is "Connected"

### Add Folder to Sync
1. Edit ~/Documents/.stignore
2. Remove line excluding desired folder
3. Save and wait ~30 seconds
4. Verify sync in Web UI

### Modify .stignore Patterns
Current exclusions:
- AREAS/
- RESOURCES/
- ARCHIVES/

To include an excluded folder, remove its line from .stignore

### Troubleshooting

**Boox not connected:**
- Check Tailscale on both devices
- Verify same network in Tailscale admin
- Restart Syncthing on Boox
- Check battery optimization (should be disabled)

**Files not syncing:**
- Check .stignore patterns
- Verify file is in synced folder
- Check file size (large files take time)
- Look for conflicts in Web UI

**Slow sync:**
- Check connection type (LAN vs relay)
- Verify Tailscale direct connection
- Check available storage on Boox

## Sync Paths

### Odin → Boox
Source: ~/Documents/
Destination: /storage/emulated/0/Books/Documents/
Synced: PROJECTS/, JOURNALS/, TODO.md

### Boox → Odin
Source: /storage/emulated/0/note/
Destination: ~/Desktop/boox-notes/
Content: Boox native notes auto-exported PDFs

Supporting Resources

• reference/syncthing-patterns.md - .stignore pattern syntax
• reference/boox-paths.md - Boox filesystem locations
• reference/tailscale-commands.md - Tailscale CLI reference
• troubleshooting/sync-issues.md - Common problems and solutions

Executable Scripts

• scripts/check-sync-status.sh - Query Syncthing API
• scripts/add-sync-folder.sh - Modify .stignore and restart
• scripts/diagnose-connection.sh - Check Tailscale and Syncthing
• scripts/force-resync.sh - Trigger full re-scan

Invocation Triggers

• "sync not working"
• "check sync status"
• "add folder to Boox"
• "modify sync configuration"
• "Boox connection issues"
• "Syncthing status"

Skill 5: sync-strategy-researcher

Purpose: Research and evaluate sync/backup solutions for devices and use cases

Description: "Research device capabilities and evaluate sync solutions (Syncthing, rclone, cloud providers) against specific criteria. Generates structured comparison and recommendation. Use when: 'research sync options', 'evaluate backup solutions', 'how to sync with [device]', 'best sync for [use case]'."

Components:

Instructions

## Research Workflow

### Phase 1: Device Capabilities
1. Identify device OS and version
2. Check native app support (iCloud, Google Drive, etc.)
3. Determine filesystem access level
4. Identify networking capabilities
5. Document storage constraints

### Phase 2: Use Case Analysis
1. Define sync direction (uni/bidirectional)
2. Identify content types (documents, media, code)
3. Determine frequency needs (real-time, daily, manual)
4. List privacy/security requirements
5. Consider availability constraints (both devices online?)

### Phase 3: Solution Evaluation
Compare options against criteria:
- **Privacy:** Data ownership and encryption
- **Cost:** Storage fees and licenses
- **Performance:** Sync speed and reliability
- **Complexity:** Setup and maintenance overhead
- **Features:** Versioning, conflict resolution, selective sync

### Phase 4: Recommendation
1. Rank solutions by criteria match
2. Identify trade-offs
3. Provide clear recommendation with rationale
4. Note fallback options
5. Estimate setup time

## Common Solutions

### Cloud Providers
- Google Drive, Dropbox, iCloud, OneDrive
- **Pros:** Easy setup, ubiquitous support
- **Cons:** Privacy concerns, storage limits, vendor lock-in

### Syncthing
- **Pros:** Privacy (P2P), unlimited, no fees, cross-platform
- **Cons:** More complex setup, requires both devices online (without always-on hub)

### rclone
- **Pros:** Flexible, supports many backends, scriptable
- **Cons:** Technical setup, manual scheduling

### Tailscale + File Sync
- **Pros:** Private network, works with any sync tool
- **Cons:** Requires Tailscale on all devices

## Documentation Template

Structure research as:
1. **Context:** Device and use case
2. **Device Capabilities:** What's possible
3. **Criteria:** What matters for this use case
4. **Options:** Solutions evaluated
5. **Comparison:** Pros/cons matrix
6. **Recommendation:** Best fit with rationale
7. **Implementation:** Next steps

Supporting Resources

• templates/sync-research.md - Research document template
• reference/sync-solutions.md - Solution catalog with capabilities
• reference/device-constraints.md - Common device limitations
• examples/boox-macos-research.md - Real example from recent work

Invocation Triggers

• "research sync options"
• "evaluate backup solutions"
• "how to sync with"
• "best sync for"
• "compare sync methods"

Implementation Considerations

For Claude Code (Anthropic's Platform)

Immediate Implementation: Create ~/.claude/skills/ directories for each skill with SKILL.md files following Anthropic's format.

Advantages:

• Built-in discovery and progressive disclosure
• Automatic invocation based on context
• Team sharing via .claude/skills/ in git
• Tool restrictions via allowed-tools parameter

Limitations:

• Specific to Claude Code CLI
• Can't customize discovery mechanism
• Limited to tools Claude Code provides

For General-Purpose Implementation

Storage: Skills can be implemented as markdown documents in RESOURCES/ or AREAS/personal-systems/skills/ for reference, with manual invocation.

Discovery: Without automatic skill invocation, use explicit requests:

• "Use the inbox-processor skill to clean my Desktop"
• "Apply the document-reviewer skill to create a Boox PDF"

Advantages:

• Platform-agnostic (works with any AI agent)
• Full control over structure and content
• Can iterate quickly without tooling

Limitations:

• Manual invocation (no automatic discovery)
• No progressive disclosure (loads full skill each time)
• Requires agent to hold skill content in context

Hybrid Approach

1. Store skills in RESOURCES/ for documentation and reference
2. Create Claude Code skills in ~/.claude/skills/ for automation
3. Keep in sync - RESOURCES/ is source of truth, skills reference it

This provides both human-readable documentation and agent automation.

Meta-Pattern: Workflow Decomposition

The key insight for creating skills from ad-hoc work:

Every workflow consists of

1. Decision Points

Human judgment or agent reasoning about:

• What category does this item belong to?
• Should this be deleted or archived?
• Is this actionable now or future?

→ Capture as: Decision trees, criteria lists, examples

2. Deterministic Operations

Scriptable actions with no ambiguity:

• File operations (move, copy, delete)
• Format conversions (markdown → PDF)
• Text transformations
• API calls

→ Capture as: Scripts, commands with parameters

3. Reference Knowledge

Conventions, formats, paths, standards:

• TODO metadata format
• Archive naming convention
• PARA decision criteria
• File paths and locations

→ Capture as: Templates, reference docs, examples

4. Workflow Orchestration

Sequence, conditions, loops, error handling:

• First do X, then Y, then Z
• If X fails, try Y
• Repeat until complete
• Validate at checkpoints

→ Capture as: Step-by-step instructions, pseudocode

Extraction Process

After completing ad-hoc work:

1. Review session: What did we do?
2. Identify patterns: What could happen again?
3. Separate concerns: Decisions vs operations vs knowledge
4. Design skill: Package all elements together
5. Validate: Would this have helped if it existed before?

Progressive Disclosure Benefits

Without skills, agent needs in context:

• Complete PARA structure understanding
• TODO metadata format specification
• Archive naming conventions
• Pandoc command syntax
• Syncthing configuration details
• Boox filesystem paths
• Annotation semantics
• File operation safety checks

Context cost: Thousands of tokens per session

With skills:

• Skill metadata: ~200 tokens (always loaded)
• Skill instructions: ~2000 tokens (loaded when relevant)
• Supporting resources: ~500 tokens each (loaded on-demand)

Context cost: ~200 tokens baseline, 2000-4000 when skill active

Result: 10x more skills can be available without context overload

Composability in Practice

Skills invoke other skills to handle sub-workflows:

Example: inbox-processor

inbox-processor (main workflow)
├── para-organizer (for filing decisions)
│   ├── validate-structure (check conventions)
│   └── create-metadata (PROJECT.md / AREA.md)
├── document-reviewer (for PDF generation)
│   ├── boox-sync-manager (verify sync)
│   └── parse-annotations (extract decisions)
└── todo-manager (for task creation)
    └── validate-metadata (check format)

Each sub-skill is independently useful and testable.

Empirical Iteration Strategy

Phase 1: Capture Validated Workflows (Current)

Build skills from recently completed work:

• ✅ Inbox processing (61 files processed successfully)
• ✅ Boox sync setup (end-to-end validated)
• ✅ Markdown → PDF → Annotate (used in both sessions)

These are proven patterns worth encoding.

Phase 2: Test and Refine

Use skills in real work:

• Does inbox-processor handle different file types?
• Does document-reviewer work for all document types?
• Does para-organizer make correct filing decisions?

Refine based on actual usage, not speculation.

Phase 3: Expand Coverage

Identify gaps during real work:

• "I wish there was a skill for X"
• "This is the third time I've done Y"
• "This workflow could be automated"

Build new skills to fill genuine needs.

Phase 4: Maintenance

Skills are living documents:

• Update when conventions change
• Add new templates based on usage
• Improve scripts when edge cases discovered
• Remove skills that aren't used

Next Steps

Immediate (This Week)

1. Create skill specifications

   • Write full SKILL.md files for 5 core skills
   • Create supporting templates and scripts
   • Test with manual invocation first

2. Implement for Claude Code

   • Create ~/.claude/skills/ directory structure
   • Convert specifications to Anthropic format
   • Test automatic discovery

3. Validate with real work

   • Use inbox-processor for next Desktop cleanup
   • Use document-reviewer for next weekly review
   • Use para-organizer for next file organization task

Short-term (This Month)

1. Build supporting infrastructure

   • Create script library (~/bin/ or similar)
   • Set up template repository
   • Document skill dependencies

2. Expand skill coverage

   • Add todo-manager skill (TODO.md operations)
   • Add weekly-reviewer skill (PARA review process)
   • Add project-bootstrapper skill (new project setup)

3. Share and iterate

   • Commit project skills to git (.claude/skills/)
   • Document lessons learned
   • Refine based on usage patterns

Long-term (This Quarter)

1. Advanced compositions

   • Build meta-skills that orchestrate multiple skills
   • Create skill dependency management
   • Design skill versioning strategy

2. Monitoring and metrics

   • Track skill invocation frequency
   • Measure time savings vs ad-hoc approach
   • Identify underutilized skills for removal

3. Team/community skills

   • Explore shared skill repositories
   • Contribute skills to open source
   • Learn from others' skill designs

Key Insights

1. Skills Make Expertise Explicit

Ad-hoc work with AI agents accumulates implicit knowledge in conversation history. Skills extract and preserve that knowledge for reuse.

2. Reproducibility Through Decomposition

Breaking workflows into decisions, operations, knowledge, and orchestration makes them repeatable without re-explaining context.

3. Progressive Disclosure Scales

With skills, agents can have 10-100x more capabilities available without context overload, because only relevant skills load fully.

4. Composition Enables Complexity

Simple, focused skills combine to handle complex workflows. This is more maintainable than monolithic instructions.

5. Empirical Validation Is Critical

Build skills from proven workflows, not anticipated needs. Real usage reveals what's worth encoding.

6. Skills Benefit Humans Too

Well-structured skills serve as documentation, onboarding material, and process guides—not just AI instructions.

7. The Pattern Transcends Implementation

Whether using Anthropic's system, custom agents, or even human processes, the skills pattern applies: package expertise for discovery and reuse.

Related Work

Primary Sources

• Anthropic Engineering Blog: "Equipping agents for the real world with Agent Skills" https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

• Claude Code Skills Documentation: https://code.claude.com/docs/en/skills

• Anthropic Skills Repository: https://github.com/anthropics/skills

Validated Workflows

• Inbox Processing Session: /Users/tnez/Documents/JOURNALS/2025-11-11--productivity-system-sync-setup.md
• PARA Restructuring: /Users/tnez/Documents/JOURNALS/2025-11-10--second-brain-restructuring.md
• Sync Research: /Users/tnez/Documents/RESOURCES/research--boox-macos-sync.md

Related Patterns

• Progressive Disclosure: UX pattern for managing complexity
• Executable Documentation: Code as specification and implementation
• Microservices: Composable, single-responsibility services
• Plugin Architectures: Extensibility through discovery and loading

Appendix: Skill Template

Use this template for creating new skills:

# Skill Name: skill-identifier

## Metadata
- **Name:** skill-identifier (lowercase, hyphens, max 64 chars)
- **Description:** What it does and when to use it (max 1024 chars, include trigger keywords)
- **Version:** 1.0.0
- **Created:** YYYY-MM-DD
- **Updated:** YYYY-MM-DD

## Purpose
One paragraph explaining the problem this skill solves.

## Invocation Triggers
- "trigger phrase 1"
- "trigger phrase 2"
- "trigger phrase 3"

## Instructions

### Workflow Overview
1. High-level step 1
2. High-level step 2
3. High-level step 3

### Detailed Steps

#### Step 1: [Name]
Detailed instructions...

Decision points:
- If X, then Y
- Otherwise Z

#### Step 2: [Name]
Detailed instructions...

Commands to run:
```bash
command --with --arguments

Step 3: [Name]

Detailed instructions...

Validation:

• [ ] Check 1
• [ ] Check 2
• [ ] Check 3

Supporting Resources

Templates

• templates/template-name.md - Description

Reference Materials

• reference/reference-name.md - Description

Examples

• examples/example-name.md - Description

Executable Scripts

script-name.sh

Purpose: What it does Usage: ./script-name.sh [args] Location: scripts/script-name.sh

Dependencies

Other Skills

• skill-name-1 (for sub-workflow)
• skill-name-2 (for validation)

External Tools

• tool-name (install via: brew install tool-name)
• tool-name (install via: pip install tool-name)

Error Handling

Common Issues

Error: Description of error Cause: Why it happens Solution: How to fix

Error: Description of error Cause: Why it happens Solution: How to fix

Validation Checklist

After skill execution, verify:

• [ ] Check 1
• [ ] Check 2
• [ ] Check 3

Examples

Example 1: [Scenario]

Input: ...
Output: ...
Notes: ...

Example 2: [Scenario]

Input: ...
Output: ...
Notes: ...

Change Log

Version 1.0.0 (YYYY-MM-DD)

• Initial implementation
• Key features: X, Y, Z

Notes

Additional context, limitations, or future enhancements.