A curated collection of personal AI skills.

Stable skills are workflows I trust and use regularly. Experimental skills are ideas under active development. Every stable skill began life as an experiment.

This repository keeps useful agent behavior version-controlled, understandable, installable, and easy to improve. It is deliberately a small collection of independent skills, not a general-purpose framework or formal skill standard.

The first skill is intent-dictation, which turns rough speech-to-text transcripts into polished, paste-ready writing while preserving the speaker's meaning.

.
├── docs/       Repository conventions and contribution guidance
├── scripts/    Installation and validation commands
└── skills/     Independently understandable skill directories

Install one skill into Claude Code:

./scripts/install intent-dictation

Install every skill:

./scripts/install --all

Experimental skills are excluded from bulk installation by default. Include them explicitly:

./scripts/install --all --include-experimental

Installing an experimental skill by name is allowed and prints a warning.

By default, the installer creates symbolic links in ~/.claude/skills, so repository edits are immediately available. Run ./scripts/install --help for target-directory and replacement options.

In Claude Code, explicitly invoke an installed skill with its slash command, such as /intent-dictation or /whoami.

Claude Code's -p/--print mode reads a prompt from stdin and writes the result to stdout. Prepend the skill's slash command to incoming data with a shell group:

{ printf '%s\n\n' '/intent-dictation'; cat; } | claude -p

This is the standard one-line pattern for a skill that transforms stdin:

producer | { printf '%s\n\n' '/skill-name'; cat; } | claude -p | consumer

For example:

pbpaste | { printf '%s\n\n' '/intent-dictation'; cat; } | claude -p | pbcopy

For a skill that needs no additional input:

printf '%s\n' '/whoami' | claude -p

Run non-interactive commands from a directory you trust. Skills that use external tools still require those tools, authentication, network access, and any applicable Claude Code permissions.

Claude Code reads installed skills directly from disk. Personal skills in Claude Chat and Cowork share an account-level list but require a manual ZIP upload through Customize > Skills. The optional workspace Skills API is a third, independent target.

uv run sync_skills.py status
uv run sync_skills.py bundle [skill-name]
uv run sync_skills.py mark-synced <skill-name>
uv run sync_skills.py mark-synced --all
uv run sync_skills.py push-api [skill-name]

status compares each canonical skill with the last manually recorded claude.ai upload. bundle creates upload-ready ZIPs in dist/; after uploading them, use mark-synced. push-api requires ANTHROPIC_API_KEY and targets only the separate workspace-level Skills API—it cannot update personal claude.ai skills.

./scripts/validate

Validation checks skill names, required files, frontmatter names, and the evaluation-case schema using Python and PyYAML.

Run every behavioral evaluation:

./scripts/eval --all

The evaluator verifies isolated installation, loads each skill's instructions and references explicitly into Claude Code, and uses a separate structured judge call to check the candidate against the case invariants. Loading instructions explicitly keeps headless CI independent of Claude Code's interactive slash-command discovery. Stable-skill failures block after one retry. Experimental-skill failures are reported but do not produce a failing exit status unless --strict-experimental is supplied.

Evaluation requires Claude Code and ANTHROPIC_API_KEY. Use ./scripts/eval --all --dry-run to inspect case discovery without making model calls. CI writes complete candidate outputs and judge explanations to downloadable JSON and JUnit artifacts.

GitHub Actions runs validation, Python unit tests, evaluator tests, installation smoke tests, and affected skill evaluations. A change within skills/<name>/ runs that skill's cases; changes to the evaluator, installer, or CI workflow run all cases; unrelated documentation changes skip model calls. Scheduled and manually dispatched workflows run the complete suite. Configure ANTHROPIC_API_KEY as a repository Actions secret, then require the Validate and Stable skill evals checks in branch protection.

Use the same changed-only selection locally:

./scripts/eval --all --changed-since origin/main

Committed skills are scanned with Snyk Agent Scan for known malicious and risky patterns, including prompt injection, suspicious downloads, credential handling, hardcoded secrets, and hidden content. Pull requests and pushes scan affected skills; scheduled and manual workflows scan the complete collection.

Agent Scan is an independent, best-effort signal rather than proof that a skill is safe or non-malicious. Review skill source before installation and run agents with least-privilege tool permissions. The scanner sends redacted contents of these public skill directories to Snyk's analysis API.

Read docs/adding-a-skill.md. The short version is: create a focused directory under skills/, add SKILL.md and README.md, include representative evaluation cases, then validate and test it in a real workflow.

Skills are expected to evolve based on real-world use. Prefer adding a failed or awkward example to the evaluations before broadening instructions abstractly.

A skill is experimental when its directory contains a non-empty EXPERIMENTAL.md. The marker should explain why the skill is experimental, its known limitations or risks, the feedback needed, and its graduation criteria.

Experimental skills are deliberately easy to try but excluded from ./scripts/install --all unless --include-experimental is supplied. Remove the marker when the graduation criteria are met.

• intent-dictation — turn rough dictation into natural writing without changing its intent.
• schedule-meeting (experimental) — interview for meeting details, check required-attendee availability, and propose bookable slots.
• whoami — report the identity of the GitHub account authenticated through gh.