From 041be56757e707a5b58909f07e36da1e642ac1c7 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Mon, 22 Jun 2026 13:15:36 -0400 Subject: [PATCH] feat: initialize agent skills repository with three starter skills Add project structure documentation (AGENTS.md) and initial README files that organize skills by bucket and invocation type (user-invoked vs model-invoked). Introduce three skills: - forge-interaction: GitHub/Gitea CLI automation for issues, PRs, releases - forge-preferences: personal forge conventions (companion to forge-interaction) - pkm-curation: Obsidian vault curation and note management Include reference docs for vault conventions, agent integration, and the invocation model that separates user-only from model-reachable skills. --- AGENTS.md | 29 +++ README.md | 12 + common/README.md | 12 + common/engineering/README.md | 9 + common/engineering/forge-interaction/SKILL.md | 212 +++++++++++++++++ common/personal/forge-preferences/SKILL.md | 31 +++ common/personal/pkm-curation/SKILL.md | 213 ++++++++++++++++++ .../references/agent-integration.md | 51 +++++ .../references/vault-conventions.md | 61 +++++ docs/invocation.md | 18 ++ 10 files changed, 648 insertions(+) create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 common/README.md create mode 100644 common/engineering/README.md create mode 100644 common/engineering/forge-interaction/SKILL.md create mode 100644 common/personal/forge-preferences/SKILL.md create mode 100644 common/personal/pkm-curation/SKILL.md create mode 100644 common/personal/pkm-curation/references/agent-integration.md create mode 100644 common/personal/pkm-curation/references/vault-conventions.md create mode 100644 docs/invocation.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..22dba56 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Steve Beaulac Skills + +A collection of agent skills (slash commands and behaviors) loaded into my agent. + +# Structure + +Skills are organized into buckets based on where they can be used and their category. + +- Use `/common/` for skills that work in all CLI agents. +- Use `/common/misc/` for skills that work in all CLI agents and are in the misc category. +- Use an agent-specific bucket only when a skill is intended for a specific agent. + +Skill are organized into categories based on their function. For example, `/common/misc/` is a bucket for miscellaneous skills that work in all CLI agents. + +If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencod/misc`. + + +## list of categories +- `engineering/` — daily code work +- `productivity/` — daily non-code workflow tools +- `misc/` — kept around but rarely used +- `personal/` — tied to my own setup, not promoted +- `in-progress/` — drafts not yet ready to ship +- `deprecated/` — no longer used + + +Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. + +Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md). diff --git a/README.md b/README.md new file mode 100644 index 0000000..619f428 --- /dev/null +++ b/README.md @@ -0,0 +1,12 @@ +# Skills + +A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's agents. + +## User-invoked + +- [pkm-curation](common/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault. + +## Model-invoked + +- [forge-preferences](common/personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. +- [forge-interaction](common/engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. diff --git a/common/README.md b/common/README.md new file mode 100644 index 0000000..ae0bdbd --- /dev/null +++ b/common/README.md @@ -0,0 +1,12 @@ +# Common Skills + +Skills that work in all CLI agents. + +## User-invoked + +- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault. + +## Model-invoked + +- [forge-preferences](personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. +- [forge-interaction](engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. diff --git a/common/engineering/README.md b/common/engineering/README.md new file mode 100644 index 0000000..12c6b13 --- /dev/null +++ b/common/engineering/README.md @@ -0,0 +1,9 @@ +# Engineering Skills + +## User-invoked + +_None yet._ + +## Model-invoked + +- [forge-interaction](forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. diff --git a/common/engineering/forge-interaction/SKILL.md b/common/engineering/forge-interaction/SKILL.md new file mode 100644 index 0000000..6891b3c --- /dev/null +++ b/common/engineering/forge-interaction/SKILL.md @@ -0,0 +1,212 @@ +--- +name: forge-interaction +description: Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea. +--- + +# Forge Interaction + +Use this skill for Git forge work on GitHub or Gitea, especially when the user asks to: + +- open a PR; +- create, list, modify, or comment on issues; +- create, list, modify, comment on, or merge pull requests; +- check CI; +- look at the repo on the forge; +- push a branch; +- publish changes; +- make or inspect a release. + +## Purpose + +Choose the correct forge CLI and use it to interact with issues, pull requests, releases, CI, and repository state. + +This skill is intended to perform forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct forge and tool. + +## Strict Decision Tree + +Follow this order every time. + +### 1. Determine the target remote + +1. If the user explicitly says which remote or forge to use, use that. +2. Else, if user/project memory or repo guidance states where to find the forge, use that. +3. Else, if a remote named `forge` exists, use `forge`. +4. Else, if the user has configured a default remote, use that. +5. Else, use `origin`. + +Useful inspection commands: + +```bash +git remote -v +git config --get checkout.defaultRemote +git config --get clone.defaultRemoteName +git config --get branch.$(git branch --show-current).remote +``` + +Interpretation: + +- A remote named `forge` is the preferred convention for the canonical forge remote. +- If no `forge` remote exists, `origin` is the fallback. +- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work. + +Only mention this selection if there is ambiguity or a conflict. + +### 2. Determine the forge type from the chosen remote + +Inspect the selected remote URL: + +```bash +git remote get-url +``` + +Classify it: + +- URLs containing `github.com` are GitHub. +- URLs containing `gitea`, or a known Gitea host from memory/project guidance, are Gitea. +- If the remote is self-hosted and ambiguous, inspect repo guidance, memory, and web/API/tool configuration before asking. + +Do not choose based on which CLI is installed. The remote determines the forge; the forge determines the CLI. + +### 3. Choose the CLI + +- If the forge is GitHub, use `gh`. +- If the forge is Gitea, use `tea`. + +Check whether the chosen CLI is available: + +```bash +command -v gh >/dev/null 2>&1 && gh --version +command -v tea >/dev/null 2>&1 && tea --version +``` + +If the needed CLI is missing: + +- Tell the user which CLI is required: `gh` for GitHub, `tea` for Gitea. +- Tell the user to install it. +- If it may already be installed but not discoverable, tell the user to add it to their `PATH`. +- Do not use the wrong CLI as a fallback. + +### 4. Check authentication/context + +Use read-only checks for the selected tool: + +```bash +# GitHub +gh auth status +gh repo view + +# Gitea +tea login list +tea repos ls +``` + +If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets. + +### 5. Do the requested forge task + +Perform the requested action with the selected CLI. + +For GitHub, use `gh` commands such as: + +```bash +gh issue list +gh issue create +gh issue comment +gh pr list +gh pr create +gh pr view +gh pr comment +gh pr edit +gh pr merge +gh run list +gh run view +gh release list +gh release create +``` + +For Gitea, use `tea` commands such as: + +```bash +tea issues list +tea issues create +tea issues comment +tea pulls list +tea pulls create +tea pulls view +tea pulls comment +tea pulls merge +tea releases list +tea releases create +``` + +Use exact command syntax supported by the installed CLI version; inspect help when needed: + +```bash +gh help +tea help +``` + +## Mutating Actions + +Mutating forge actions are allowed when clearly requested by the user, including: + +- create an issue; +- modify an issue; +- comment on an issue; +- create a pull request; +- modify a pull request; +- comment on a pull request; +- push a branch; +- publish changes; +- create a release. + +Still be careful with destructive or high-impact actions: + +- Ask before deleting branches, tags, releases, issues, or repositories. +- Ask before force-pushing. +- Ask before merging a PR unless the user explicitly asked to merge it. +- Ask before overwriting existing release assets or tags. + +## Branch and PR Preparation + +Before creating or updating a PR: + +1. Select the remote using the strict decision tree. +2. Select the CLI from the remote's forge type. +3. Inspect branch state and upstream tracking. +4. Inspect the diff against the target branch. +5. Read the PR template if one exists. +6. Push the branch if needed and requested by the workflow. +7. Create or update the PR. + +Useful local inspection: + +```bash +git status --short --branch +git branch -vv +git diff --stat +git diff --check +``` + +## Output Style + +Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result. + +Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include: + +- selected remote; +- detected forge; +- selected CLI; +- reason for the choice; +- what the user needs to fix, if anything. + +## Companion Personal Skill + +Personal forge preferences should live in a separate skill or memory entry, not in this general skill. That companion skill/memory may specify things like: + +- preferred default remote conventions; +- known personal Gitea or GitHub hosts; +- preferred issue/PR/release styles; +- project-specific forge rules. + +This general skill should consume that memory/guidance when present, but keep the generic decision tree above as the fallback. diff --git a/common/personal/forge-preferences/SKILL.md b/common/personal/forge-preferences/SKILL.md new file mode 100644 index 0000000..2b5047f --- /dev/null +++ b/common/personal/forge-preferences/SKILL.md @@ -0,0 +1,31 @@ +--- +name: forge-preferences +description: Use with forge-interaction to apply Steve's personal or project-specific GitHub/Gitea remote, CLI, issue, PR, and release preferences. +--- + +# Forge Preferences + +Use this companion skill with `/forge-interaction` when personal or project-specific forge preferences are relevant. + +## Purpose + +Store personal conventions that should not live in the generic forge interaction skill. + +## Current Preferences + +- If a remote named `forge` exists, treat it as the canonical forge remote. +- If no `forge` remote exists, use the user's configured default remote when available. +- If no default remote is configured, use `origin`. +- Use the forge type of the selected remote to choose the CLI: + - GitHub → `gh` + - Gitea → `tea` +- If the correct CLI is missing, tell the user to install it or add it to `PATH`. +- Do not use the wrong CLI as a fallback. + +## Open Questions To Fill In Later + +- Known personal Gitea hosts. +- GitHub usernames or organizations. +- Preferred PR title/body format. +- Preferred issue labels and milestones. +- Release naming and tagging conventions. diff --git a/common/personal/pkm-curation/SKILL.md b/common/personal/pkm-curation/SKILL.md new file mode 100644 index 0000000..3e08f27 --- /dev/null +++ b/common/personal/pkm-curation/SKILL.md @@ -0,0 +1,213 @@ +--- +name: pkm-curation +description: Curate an Obsidian-style personal knowledge vault by classifying notes, normalizing frontmatter, improving structure, extracting atomic notes, and adding meaningful wikilinks. +disable-model-invocation: true +--- + +# PKM Curation + +Use this skill when working inside a Markdown-first vault that values curation over collection. + +## Goals + +- Turn raw notes into clear, reusable notes. +- Keep new notes consistent with vault conventions. +- Strengthen the link graph with meaningful `[[wikilinks]]` syntax `[[Note Title]]`. +- Extract atomic notes from long or mixed-topic notes. +- Avoid unnecessary reorganization and weak links. + +## Read This First + +- Read `AGENTS.md` in the current repo scope before editing notes. +- Read `references/vault-conventions.md` when normalizing metadata, deciding note types, or choosing folders. +- Read `references/agent-integration.md` when running this skill through an agent. +- Keep changes small and reviewable. +- Keep file operations local to the vault unless the user explicitly asks otherwise. + +## Workflows + +## Search for notes + +```bash +# Search by filename +fd --type f ".md" "$HOME/Documents/nca-notes" | rg -i "keyword" + +# Search by content +rg -l "keyword" "$HOME/Documents/nca-notes" --include "*.md" +``` + +## Curate existing note +1. Inspect the target note or note set. +2. Identify the note type: inbox, source, atomic, project, daily, or reference. +3. Normalize frontmatter and basic structure. +4. Clarify the title if the current one is vague or timestamp-like. +5. Summarize or distill the note if it mixes too many ideas. +6. Add or suggest meaningful `[[wikilinks]]` to related notes. +7. If a note contains multiple durable ideas, extract 1-3 atomic notes. +8. Suggest moving the note only if the destination is clearly better. + +## Find related notes + +Search for `[[Note Title]]` across the vault to find backlinks: + +```bash +rg -l "\\[\\[Note Title\\]\\]" "$HOME/Documents/nca-notes" --include "*.md" +``` + +### Find index notes + +```bash +fd --type f "Index" "$HOME/Documents/nca-notes" +``` + +## Operating Rules + +- Prefer reorganization over curation. +- Do not move, rename, or delete many notes at once unless the user asks. +- Do not invent links based only on shared words. +- Preserve the user's voice unless the user asks for a rewrite. +- Keep source material and evergreen ideas separate when possible. +- Treat `Inbox/` as temporary capture, not long-term storage. +- Preserve all command blocks, code snippets, configuration directives, and + step-by-step instructions verbatim. Do not summarize or condense them. +- For reference/source notes: add a brief overview at the top, but keep the + original commands and details intact below. Completeness > brevity. +- Read every file completely before editing. Do not rely on head/tail, + heading-only scans, or partial reads to judge a file's content. +- For any file you plan to move, rename, or modify, run `cat` on the full file + first. Only then decide what stays, what moves, and what changes. + +## Note-Type Heuristics + +### Inbox note + +Use when the note is raw capture, partial thinking, copied text, or an unprocessed link dump. + +Actions: +- clean obvious structure issues +- add frontmatter if missing +- classify for later promotion +- avoid over-polishing unless requested + +### Source note + +Use when the note is based on an article, video, book, paper, transcript, or other external material. + +Actions: +- keep source context intact +- summarize key takeaways +- extract reusable ideas into separate atomic notes +- link to related concepts and projects + +### Atomic note + +Use when the note captures one durable idea, concept, claim, pattern, or insight. + +Actions: +- ensure one main idea per note +- make the title concept-focused +- add links to neighboring ideas +- keep it concise and self-contained + +### Project note + +Use when the note supports active work, planning, resources, decisions, or tasks. + +Actions: +- preserve project context +- link tasks to the project note +- avoid turning active project logistics into evergreen notes unless there is a reusable insight + +### Daily note + +Use when the note is date-based and captures activity, learning, tasks, or reflection for a single day. + +Actions: +- preserve chronology +- link out to durable notes rather than stuffing ideas into the daily note + +## Linking Guidance + +Add links only when they express one of these relationships: + +- concept to broader concept +- source note to extracted idea +- project note to relevant knowledge note +- daily note to work done or ideas learned +- sibling concepts that genuinely inform one another + +When linking, prefer existing notes over creating speculative new ones. + +## Extraction Guidance + +Extract atomic notes when a note contains: + +- multiple durable ideas +- a strong claim hidden in raw notes +- a reusable method, distinction, or definition +- a concept that should be linked from many places + +Keep extracted notes short. One note, one idea. + +## Common Tasks + +### Curate one note + +- inspect the note +- identify note type +- normalize frontmatter +- tighten headings and summary +- add a few strong links +- suggest extracted atomic notes if warranted +- locate the target file in the vault +- inspect nearby related notes before adding links +- patch the note in place +- return a short summary of edits and suggested follow-up notes + +### Curate an inbox batch + +- process a small batch, usually 5-10 notes +- classify each note +- normalize metadata +- suggest which notes should stay raw, become source notes, or become atomic notes +- avoid large folder reshuffles unless the pattern is clear +- enumerate a small set of `Inbox/` notes +- process them one at a time +- stop and summarize after each batch + +### Review recent notes + +- inspect recently edited notes +- identify missing links and vague titles +- flag notes with mixed concerns +- suggest a small set of follow-up curation actions +- search by recent filenames or recent folders when file metadata is available +- keep edits conservative and return a review summary + +### Serendipity review + +- choose a note from the vault +- summarize it briefly +- compare it to the user's current topic or active project +- suggest only high-confidence connections +- pick one note from a user-specified folder or from curated folders only +- avoid randomizing across obviously raw capture unless the user asks for that + +## Output Style + +When responding to the user: + +- state what kind of note you think it is +- summarize the curation changes you made or recommend +- list any extracted notes to create +- list meaningful links added or suggested +- mention any move or rename separately before doing it +- name the file or files touched +- separate completed edits from suggested next actions +- call out anything that still needs user confirmation + +## If You Need More Context + +If the vault structure is unclear, inspect folders and a few nearby notes before editing. +If note conventions appear to conflict, follow the most local `AGENTS.md` instructions in scope. +Don't guess at user preferences. When in doubt, ask the user before making big changes or suggesting speculative links. diff --git a/common/personal/pkm-curation/references/agent-integration.md b/common/personal/pkm-curation/references/agent-integration.md new file mode 100644 index 0000000..a75f378 --- /dev/null +++ b/common/personal/pkm-curation/references/agent-integration.md @@ -0,0 +1,51 @@ +--- +id: pkm-curation-agent-integration +aliases: + - PKM Curation agent Integration +tags: + - knowledge-management + - reference +area: Personal Knowledge Management +project: +--- + +# Agent Integration + +## Purpose + +This skill should be usable from any agent, and it should also fit chat environments where the agent as tool access. + +## Recommended Role + +- batch curation, targeted note cleanup, folder reviews, and repeatable vault maintenance +- interactive note refinement, serendipity review, and exploratory linking sessions +- editor-side entry point that delegates vault actions to agent where possible + +## Preferred Behaviors + +- search the vault before proposing links +- inspect nearby notes before creating new ones +- patch files directly when the requested change is clear +- summarize edits in plain Markdown +- ask before removing any content or links from a note +- ask before moving, renaming, or creating many files + +## Good Task Shapes + +- curate a specific note +- process a small `Inbox/` batch +- review recent notes for missing links +- extract atomic notes from one source note +- run a serendipity review against a current topic + +## Avoid + +- large autonomous folder reorganizations +- broad speculative linking passes +- converting every long note into atomic notes +- changing note titles without stating why + +## Portability Guidance + +- keep the workflow in `SKILL.md` tool-agnostic where possible +- prefer small deterministic file edits so the skill remains portable to other `SKILL.md`-based agents diff --git a/common/personal/pkm-curation/references/vault-conventions.md b/common/personal/pkm-curation/references/vault-conventions.md new file mode 100644 index 0000000..c86f8e3 --- /dev/null +++ b/common/personal/pkm-curation/references/vault-conventions.md @@ -0,0 +1,61 @@ +--- +id: pkm-curation-vault-conventions +aliases: + - PKM Curation Vault Conventions +tags: + - knowledge-management + - obsidian + - reference + - ai +area: Personal Knowledge Management +project: +--- + +# Vault Conventions + +## Required Frontmatter + +All notes should include YAML frontmatter with: + +```yaml +--- +id: unique-id +aliases: [] +tags: [] +area: Primary area/domain +project: [[Project Note]] +--- +``` + +Use an empty value for `project:` when there is no relevant project note. + +## Core Principles + +- Markdown-first +- explicit `[[wikilinks]]` +- atomic notes for durable ideas +- project, topic, and date-based organization +- consistency over novelty + +## Folder Roles + +- `Inbox/`: raw capture and unprocessed notes +- `Dailies/`: day-specific notes and reflection +- `Templates/`: note templates +- `Knowledge/`: preferred home for evergreen atomic notes if the folder exists or is created +- project/topic folders: active work and structured reference material + +## Task Conventions + +- Use Markdown task items: `- [ ] Task description [[Project Name]]` +- Add status and priority tags where useful +- Use `due:: YYYY-MM-DD` for due dates +- Add `start::` and `end::` only when explicitly requested or when tracking active work + +## Curation Heuristics + +- A saved thing is not yet a knowledge note. +- A source note is not the same as an evergreen note. +- A link should reflect a real conceptual or project relationship. +- A long note may remain long if it is reference material; only extract notes when reuse is likely. +- Prefer gradual improvement over mass refactoring. diff --git a/docs/invocation.md b/docs/invocation.md new file mode 100644 index 0000000..c434516 --- /dev/null +++ b/docs/invocation.md @@ -0,0 +1,18 @@ +# Model-invoked vs user-invoked + +Every `SKILL.md` in this repo is a skill. The one axis that splits them is **invocation** — who can reach it: + +- **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…"). +- **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.) + +Because a user-invoked skill has no description, nothing but the human can reach it — no other skill can fire it. So a user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill. + +Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. + +## Dependencies between them + +Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. + +## Passive vs active domain work + +Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`.