MCPInstall

secretary

Capture and manage decisions, commitments, ideas, sessions, and knowledge. The core data management skill for the secretary plugin.

Installs
60
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/mwguerra/claude-code-plugins --skill secretary
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads secretary automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Secretary Skill

Capture commitments, record decisions, track ideas, manage sessions, and maintain the full knowledge base.

When to Use

  • Analyzing conversation for commitments, decisions, or ideas
  • Recording a new commitment, decision, or idea manually
  • Updating the status of a tracked item (complete, defer, cancel)
  • Managing queue items and worker processing
  • Updating the knowledge graph
  • Managing goals and milestones
  • Accessing or managing encrypted memory entries
  • Checking worker and queue status

Database Locations

# Main database
SECRETARY_DB_PATH="$HOME/.claude/secretary/secretary.db"

# Encrypted memory database
SECRETARY_MEMORY_DB_PATH="$HOME/.claude/secretary/memory.db"

# Configuration
SECRETARY_CONFIG_FILE="$HOME/.claude/secretary.json"

# Scripts
PLUGIN_ROOT="$HOME/.claude/plugins/secretary"  # or wherever installed

Commitment Management

Recording a Commitment

-- Get next ID
SELECT 'C-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM commitments;

-- Insert
INSERT INTO commitments (
    id, title, description, source_type, source_session_id,
    source_context, project, assignee, stakeholder,
    due_date, due_type, priority, status
) VALUES (
    :id, :title, :description, :source_type, :session_id,
    :context, :project, :assignee, :stakeholder,
    :due_date, :due_type, :priority, 'pending'
);

Updating Commitments

-- Complete
UPDATE commitments SET
    status = 'completed', completed_at = datetime('now'), updated_at = datetime('now')
WHERE id = :id;

-- Defer
UPDATE commitments SET
    status = 'deferred', deferred_until = :date,
    deferred_count = deferred_count + 1, updated_at = datetime('now')
WHERE id = :id;

-- Cancel
UPDATE commitments SET
    status = 'canceled', updated_at = datetime('now')
WHERE id = :id;

-- Change priority
UPDATE commitments SET
    priority = :new_priority, updated_at = datetime('now')
WHERE id = :id;

Listing Commitments

-- All pending (sorted by priority)
SELECT id, title, due_date, priority, project, status
FROM commitments
WHERE status IN ('pending', 'in_progress')
ORDER BY
    CASE WHEN due_date < date('now') THEN 0 ELSE 1 END,
    CASE priority WHEN 'critical' THEN 1 WHEN 'high' THEN 2 WHEN 'medium' THEN 3 ELSE 4 END,
    due_date ASC;

-- By project
SELECT id, title, due_date, priority, status
FROM commitments
WHERE project = :project AND status IN ('pending', 'in_progress')
ORDER BY priority DESC;

-- Overdue only
SELECT id, title, due_date, priority, project
FROM commitments
WHERE status IN ('pending', 'in_progress') AND due_date < date('now')
ORDER BY due_date ASC;

Detection Patterns

Look for these phrases in conversation:

Commitments:

  • "I will...", "I'll...", "Let me..."
  • "We should...", "We need to..."
  • "TODO:", "FIXME:", "Follow up on..."
  • "Don't forget to...", "Make sure to..."
  • "Remind me to...", "Get back to..."

Decision Recording

Recording a Decision

-- Get next ID
SELECT 'D-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM decisions;

-- Insert
INSERT INTO decisions (
    id, title, description, rationale, alternatives,
    consequences, category, scope, project,
    source_session_id, source_context, status, tags
) VALUES (
    :id, :title, :description, :rationale, :alternatives_json,
    :consequences, :category, :scope, :project,
    :session_id, :context, 'active', :tags_json
);

Updating Decisions

-- Supersede
UPDATE decisions SET
    status = 'superseded', superseded_by = :new_decision_id,
    updated_at = datetime('now')
WHERE id = :old_id;

-- Reverse
UPDATE decisions SET
    status = 'reversed', updated_at = datetime('now')
WHERE id = :id;

Detection Patterns

Decisions:

  • "Decided to...", "The decision is..."
  • "Let's go with...", "We'll use..."
  • "The approach is...", "The plan is..."
  • "From now on...", "Going forward..."
  • "Instead of...", "Rather than..."

Extraction Process

  1. Identify decision phrase
  2. Extract what was decided
  3. Look for rationale ("because", "since", "due to")
  4. Identify alternatives mentioned ("instead of", "rather than")
  5. Categorize: architecture, process, technology, design
  6. Determine scope: project-wide, feature, component

Idea Capture

Recording an Idea

-- Get next ID
SELECT 'I-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM ideas;

-- Insert
INSERT INTO ideas (
    id, title, description, idea_type, category,
    project, source_session_id, source_context,
    priority, effort, potential_impact, status, tags
) VALUES (
    :id, :title, :description, :type, :category,
    :project, :session_id, :context,
    :priority, :effort, :impact, 'captured', :tags_json
);

Updating Ideas

-- Start exploring
UPDATE ideas SET status = 'exploring', updated_at = datetime('now') WHERE id = :id;

-- Park for later
UPDATE ideas SET status = 'parked', updated_at = datetime('now') WHERE id = :id;

-- Mark done
UPDATE ideas SET status = 'done', updated_at = datetime('now') WHERE id = :id;

-- Discard
UPDATE ideas SET status = 'discarded', updated_at = datetime('now') WHERE id = :id;

Goal Management

Creating a Goal

SELECT 'G-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM goals;

INSERT INTO goals (
    id, title, description, goal_type, timeframe,
    parent_goal_id, project, target_value, target_unit,
    target_date, status, milestones, related_commitments
) VALUES (
    :id, :title, :description, :type, :timeframe,
    :parent_id, :project, :target_value, :target_unit,
    :target_date, 'active', :milestones_json, :related_json
);

Updating Goal Progress

UPDATE goals SET
    current_value = :value,
    progress_percentage = ROUND(100.0 * :value / NULLIF(target_value, 0), 1),
    updated_at = datetime('now')
WHERE id = :id;

Activity Timeline

Event Types

TypeDescription
session_startNew session began
session_endSession completed
commitmentCommitment extracted
commitment_completedCommitment marked done
decisionDecision recorded
goal_progressGoal updated
goal_completedGoal finished
commitGit commit made
external_changeChange detected from outside

Recording Activity

INSERT INTO activity_timeline (
    activity_type, entity_type, entity_id,
    project, title, details, session_id
) VALUES (:type, :entity_type, :entity_id, :project, :title, :details_json, :session_id);

Knowledge Graph

Node Types

TypeDescription
projectSoftware projects
technologyLanguages, frameworks, tools
personTeam members, stakeholders
conceptArchitectural patterns, methodologies
toolDevelopment tools, services

Creating/Updating Nodes

SELECT 'N-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM knowledge_nodes;

INSERT INTO knowledge_nodes (id, name, node_type, description, properties, aliases)
VALUES (:id, :name, :type, :description, :properties_json, :aliases_json)
ON CONFLICT(id) DO UPDATE SET
    description = COALESCE(:description, description),
    interaction_count = interaction_count + 1,
    last_interaction = datetime('now'),
    updated_at = datetime('now');

Creating/Updating Edges

SELECT 'E-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, 3) AS INTEGER)), 0) + 1) as next_id
FROM knowledge_edges;

INSERT INTO knowledge_edges (id, source_node_id, target_node_id, relationship, strength, properties)
VALUES (:id, :source, :target, :relationship, :strength, :properties_json)
ON CONFLICT(id) DO UPDATE SET
    strength = MIN(strength + 0.1, 1.0),
    updated_at = datetime('now');

Relationship Types

  • uses - Project uses technology
  • knows - Person knows technology
  • owns - Person owns project
  • depends_on - Project depends on another
  • related_to - General relationship

Encrypted Memory

Manage sensitive data via the memory manager script:

SCRIPT="$PLUGIN_ROOT/scripts/memory-manager.sh"

# Add a memory entry
bash "$SCRIPT" add "AWS API Key" "AKIA..." api_key "my-project" "aws,production"

# Search memory
bash "$SCRIPT" search "API key"

# List by category
bash "$SCRIPT" list credential
bash "$SCRIPT" list api_key my-project

# View a specific entry
bash "$SCRIPT" show 1

# Delete an entry
bash "$SCRIPT" delete 1

# Check encryption status
bash "$SCRIPT" status

Categories: credential, api_key, ip_address, phone, secret, note, general

Queue Operations

Check Queue Status

SELECT status, COUNT(*) as count
FROM queue
GROUP BY status;

Force Process Queue

bash "$PLUGIN_ROOT/scripts/process-queue.sh" --limit 10

Check Worker State

SELECT last_run_at, last_success_at, last_error,
    items_processed, total_runs,
    last_vault_sync_at, last_github_refresh_at
FROM worker_state WHERE id = 1;

Daily Notes

-- Create or update daily note
INSERT INTO daily_notes (id, date)
VALUES (date('now'), date('now'))
ON CONFLICT(id) DO NOTHING;

-- Update with session data
UPDATE daily_notes SET
    sessions_count = sessions_count + 1,
    last_activity_at = datetime('now'),
    updated_at = datetime('now')
WHERE date = date('now');

ID Generation

# Pattern for all entity IDs
# C-0001 for commitments
# D-0001 for decisions
# I-0001 for ideas
# G-0001 for goals
# P-0001 for patterns
# N-0001 for knowledge nodes
# E-0001 for knowledge edges

# SQL pattern to get next ID:
SELECT '<PREFIX>-' || printf('%04d', COALESCE(MAX(CAST(SUBSTR(id, LENGTH('<PREFIX>') + 2) AS INTEGER)), 0) + 1)
FROM <table>;

Output Guidelines

When reporting captured items:

## Captured

### Commitment
- **ID:** C-0025
- **Title:** Implement caching layer
- **Priority:** High
- **Due:** This week
- **Source:** Conversation

### Decision
- **ID:** D-0018
- **Title:** Use Redis for caching
- **Category:** Architecture
- **Rationale:** Better performance for distributed systems

### Idea
- **ID:** I-0015
- **Title:** GraphQL migration
- **Type:** Exploration
- **Impact:** High

Silence Mode

When operating via hooks (capture.sh), work silently:

  • Do not output unless explicitly requested
  • Log to activity_timeline for later review
  • Items are reviewed via /secretary:status or /secretary:briefing

Error Handling

  • Skip malformed or ambiguous items during extraction
  • Log extraction failures to debug log
  • Continue processing on individual item failures
  • Retry failed queue items up to 3 times
  • Expire unprocessed queue items after 24 hours

Related Commands

  • /secretary:track - Manage commitments (add, complete, defer, list)
  • /secretary:decide - Record decisions with rationale
  • /secretary:idea - Capture ideas
  • /secretary:status - Show full dashboard
  • /secretary:briefing - Generate context briefing
  • /secretary:memory - Manage encrypted memory
  • /secretary:worker - Check/trigger worker processing

FAQ

What does the secretary skill do?

Capture and manage decisions, commitments, ideas, sessions, and knowledge. The core data management skill for the secretary plugin.

How do I install secretary?

Run npx skills add https://github.com/mwguerra/claude-code-plugins --skill secretary in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/secretary/ (personal) or .claude/skills/secretary/ (project).

Which AI agents can use secretary?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is secretary safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains secretary?

It is published by mwguerra in mwguerra/claude-code-plugins. It has 60 recorded installs.

More from mwguerra/claude-code-plugins

View all →

filament-resource

mwguerra/claude-code-plugins

Generate FilamentPHP v4 resources with form, table, relation managers, and actions

1.2K installs

resource

mwguerra/claude-code-plugins

Generate FilamentPHP v4 resources with form, table, relation managers, and actions

214 installs

forms

mwguerra/claude-code-plugins

Create FilamentPHP v4 forms with fields, validation, sections, tabs, and relationships

95 installs

tables

mwguerra/claude-code-plugins

Open the skill to read its SKILL.md instructions.

88 installs

actions

mwguerra/claude-code-plugins

Create FilamentPHP v4 actions with modals, confirmation, forms, and bulk operations

76 installs

widgets

mwguerra/claude-code-plugins

Create FilamentPHP v4 dashboard widgets - stats overviews, charts, and custom components

Data & Databases75 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs