Detailed changes
@@ -0,0 +1,96 @@
+---
+name: authoring-skills
+description: Creates well-structured Agent Skills following best practices. Use when writing new skills, reviewing existing skills, or when the user mentions skill authoring or Skills.
+compatibility: Requires filesystem access to create skill directories and files
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+ version: "1.0"
+---
+
+Skills extend agent capabilities through a simple folder structure. Every skill requires a `SKILL.md` file with YAML frontmatter and markdown instructions.
+
+```
+skill-name/
+├── SKILL.md # Required: metadata + instructions
+├── scripts/ # Optional: executable code
+├── references/ # Optional: documentation
+└── assets/ # Optional: templates, resources
+```
+
+1. Conciseness: The context window is shared. Challenge every token: "Does the agent really need this?"
+2. Progressive disclosure: Load metadata at startup, instructions when activated, resources only when needed
+3. Appropriate freedom: Match specificity to task fragility (see [patterns.md](references/patterns.md))
+
+## Required frontmatter
+
+```yaml
+---
+name: processing-pdfs
+description: Extracts text and tables from PDF files. Use when working with PDFs or document extraction.
+---
+```
+
+### `name`
+
+- 1-64 characters
+- Lowercase letters, numbers, hyphens only
+- No start/end with hyphen, no consecutive hyphens
+- Must match parent directory name
+- **Prefer gerund form**: `processing-pdfs`, `analyzing-data`, `writing-documentation`
+
+### `description`
+
+- 1-1024 characters, non-empty
+- Must be third person: "Extracts...", "Generates...", "Manages..."
+- Include what it does AND when to use it
+- Include trigger keywords for discovery
+- No markdown formatting
+
+**Good**: `Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
+
+**Bad**: `Helps with PDFs.`
+
+### Optional frontmatter
+
+```yaml
+license: Apache-2.0
+compatibility: Requires git and docker
+metadata:
+ author: your-name
+ version: "1.0"
+allowed-tools: Bash(git:*) Read
+```
+
+## Body content guidelines
+
+- Keep under 500 lines (move details to reference files)
+- No format restrictions—write what helps agents perform the task
+- Assume the agent is intelligent; only add context it doesn't already have
+- Use consistent terminology throughout
+
+### Recommended sections
+
+- Step-by-step instructions
+- Input/output examples
+- Common edge cases
+- Links to reference files for advanced details
+
+## Progressive disclosure structure
+
+```markdown
+# Quick start
+[Essential instructions here]
+
+## Advanced features
+**Form filling**: See [FORMS.md](references/FORMS.md)
+**API reference**: See [REFERENCE.md](references/REFERENCE.md)
+```
+
+Keep file references **one level deep** from SKILL.md. Avoid nested reference chains.
+
+## Detailed guidance
+
+- **Technical specification**: See [specification.md](references/specification.md)
+- **Common patterns**: See [patterns.md](references/patterns.md)
+- **Pre-publish checklist**: See [checklist.md](references/checklist.md)
@@ -0,0 +1,27 @@
+- [ ] `name` follows naming rules (lowercase, hyphens, 1-64 chars)
+- [ ] `name` matches parent directory name
+- [ ] `name` uses gerund form when possible (`processing-pdfs`)
+- [ ] `description` is third person ("Extracts...", not "I extract...")
+- [ ] `description` includes what it does AND when to use it
+- [ ] `description` has no markdown formatting
+- [ ] `description` includes trigger keywords for discovery
+- [ ] SKILL.md body is under 500 lines
+- [ ] Additional details are in separate reference files
+- [ ] No time-sensitive information (or in "old patterns" section)
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+- [ ] File references are one level deep from SKILL.md
+- [ ] Reference files >100 lines have table of contents
+- [ ] Progressive disclosure used appropriately
+- [ ] Workflows have clear steps
+
+## Scripts (if applicable)
+
+- [ ] Scripts solve problems rather than punt to agent
+- [ ] Error handling is explicit and helpful
+- [ ] No magic constants (all values justified/documented)
+- [ ] Required packages listed and verified as available
+- [ ] Scripts have clear documentation
+- [ ] No Windows-style paths (use forward slashes)
+- [ ] Validation/verification steps for critical operations
+- [ ] Feedback loops included for quality-critical tasks
@@ -0,0 +1,214 @@
+# Common Patterns
+
+## Contents
+
+- [Degrees of freedom](#degrees-of-freedom)
+- [Template pattern](#template-pattern)
+- [Examples pattern](#examples-pattern)
+- [Conditional workflow pattern](#conditional-workflow-pattern)
+- [Workflow with checklist](#workflow-with-checklist)
+- [Feedback loops](#feedback-loops)
+- [Domain-specific organization](#domain-specific-organization)
+
+## Degrees of freedom
+
+Match specificity to task fragility.
+
+### High freedom (text instructions)
+
+Use when multiple approaches are valid or decisions depend on context.
+
+```markdown
+## Code review process
+
+1. Analyze the code structure and organization
+2. Check for potential bugs or edge cases
+3. Suggest improvements for readability
+4. Verify adherence to project conventions
+```
+
+### Medium freedom (pseudocode/parameterized scripts)
+
+Use when a preferred pattern exists but some variation is acceptable.
+
+````markdown
+## Generate report
+
+Use this template and customize as needed:
+
+```python
+def generate_report(data, format="markdown", include_charts=True):
+ # Process data
+ # Generate output in specified format
+```
+````
+
+### Low freedom (specific scripts)
+
+Use when operations are fragile, consistency is critical, or a specific sequence must be followed.
+
+````markdown
+## Database migration
+
+Run exactly this script:
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+Do not modify the command or add additional flags.
+````
+
+## Template pattern
+
+Provide output format templates. Match strictness to requirements.
+
+**Strict** (API responses, data formats):
+
+````markdown
+## Report structure
+
+ALWAYS use this exact template:
+
+```markdown
+# [Title]
+
+## Executive summary
+
+[One paragraph]
+
+## Key findings
+
+- Finding 1
+- Finding 2
+```
+````
+
+**Flexible** (when adaptation is useful):
+
+````markdown
+## Report structure
+
+Sensible default format—adapt based on analysis:
+
+```markdown
+# [Title]
+
+## Executive summary
+
+## Key findings
+```
+
+Adjust sections as needed.
+````
+
+## Examples pattern
+
+Provide input/output pairs for output-quality-dependent tasks.
+
+````markdown
+## Commit message format
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly
+Output:
+
+```
+fix(reports): correct date formatting in timezone conversion
+```
+````
+
+## Conditional workflow pattern
+
+Guide through decision points:
+
+```markdown
+## Document modification
+
+1. Determine the modification type:
+
+ **Creating new content?** → Follow "Creation workflow"
+ **Editing existing?** → Follow "Editing workflow"
+
+2. Creation workflow:
+ - Use docx-js library
+ - Build from scratch
+ - Export to .docx
+
+3. Editing workflow:
+ - Unpack existing document
+ - Modify XML directly
+ - Validate after each change
+```
+
+## Workflow with checklist
+
+For complex multi-step tasks:
+
+````markdown
+## Form filling workflow
+
+Copy this checklist:
+
+```
+- [ ] Step 1: Analyze form (run analyze_form.py)
+- [ ] Step 2: Create field mapping
+- [ ] Step 3: Validate mapping
+- [ ] Step 4: Fill the form
+- [ ] Step 5: Verify output
+```
+
+**Step 1: Analyze the form**
+Run: `python scripts/analyze_form.py input.pdf`
+````
+
+## Feedback loops
+
+Run validator → fix errors → repeat. This pattern greatly improves output quality.
+
+```markdown
+## Document editing process
+
+1. Make edits to document
+2. **Validate immediately**: `python scripts/validate.py`
+3. If validation fails:
+ - Review the error message
+ - Fix the issues
+ - Validate again
+4. **Only proceed when validation passes**
+```
+
+## Domain-specific organization
+
+For skills with multiple domains, organize by domain to avoid loading irrelevant context.
+
+```
+bigquery-skill/
+├── SKILL.md
+└── reference/
+ ├── finance.md
+ ├── sales.md
+ ├── product.md
+ └── marketing.md
+```
+
+```markdown
+# SKILL.md
+
+## Available datasets
+
+**Finance**: Revenue, billing → See [reference/finance.md](reference/finance.md)
+**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)
+```
+
+When user asks about revenue, the agent reads only finance.md.
@@ -0,0 +1,259 @@
+# Specification
+
+This document defines the Agent Skills format.
+
+## Contents
+
+- [Directory structure](#directory-structure)
+- [SKILL.md format](#skillmd-format)
+ - [Frontmatter (required)](#frontmatter-required)
+ - [Body content](#body-content)
+- [Optional directories](#optional-directories)
+- [Progressive disclosure](#progressive-disclosure)
+- [File references](#file-references)
+- [Validation](#validation)
+
+## Directory structure
+
+A skill is a directory containing at minimum a `SKILL.md` file:
+
+```
+skill-name/
+└── SKILL.md # Required
+```
+
+<Tip>
+ You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill.
+</Tip>
+
+## SKILL.md format
+
+The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
+
+### Frontmatter (required)
+
+```yaml
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+With optional fields:
+
+```yaml
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+license: Apache-2.0
+metadata:
+ author: example-org
+ version: "1.0"
+---
+```
+
+| Field | Required | Constraints |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
+| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
+| `license` | No | License name or reference to a bundled license file. |
+| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
+| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
+| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) |
+
+#### `name` field
+
+The required `name` field:
+
+- Must be 1-64 characters
+- May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`)
+- Must not start or end with `-`
+- Must not contain consecutive hyphens (`--`)
+- Must match the parent directory name
+
+Valid examples:
+
+```yaml
+name: pdf-processing
+```
+
+```yaml
+name: data-analysis
+```
+
+```yaml
+name: code-review
+```
+
+Invalid examples:
+
+```yaml
+name: PDF-Processing # uppercase not allowed
+```
+
+```yaml
+name: -pdf # cannot start with hyphen
+```
+
+```yaml
+name: pdf--processing # consecutive hyphens not allowed
+```
+
+#### `description` field
+
+The required `description` field:
+
+- Must be 1-1024 characters
+- Should describe both what the skill does and when to use it
+- Should include specific keywords that help agents identify relevant tasks
+
+Good example:
+
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+```
+
+Poor example:
+
+```yaml
+description: Helps with PDFs.
+```
+
+#### `license` field
+
+The optional `license` field:
+
+- Specifies the license applied to the skill
+- We recommend keeping it short (either the name of a license or the name of a bundled license file)
+
+Example:
+
+```yaml
+license: Proprietary. LICENSE.txt has complete terms
+```
+
+#### `compatibility` field
+
+The optional `compatibility` field:
+
+- Must be 1-500 characters if provided
+- Should only be included if your skill has specific environment requirements
+- Can indicate intended product, required system packages, network access needs, etc.
+
+Examples:
+
+```yaml
+compatibility: Designed for Claude Code (or similar products)
+```
+
+```yaml
+compatibility: Requires git, docker, jq, and access to the internet
+```
+
+<Note>
+ Most skills do not need the `compatibility` field.
+</Note>
+
+#### `metadata` field
+
+The optional `metadata` field:
+
+- A map from string keys to string values
+- Clients can use this to store additional properties not defined by the Agent Skills spec
+- We recommend making your key names reasonably unique to avoid accidental conflicts
+
+Example:
+
+```yaml
+metadata:
+ author: example-org
+ version: "1.0"
+```
+
+#### `allowed-tools` field
+
+The optional `allowed-tools` field:
+
+- A space-delimited list of tools that are pre-approved to run
+- Experimental. Support for this field may vary between agent implementations
+
+Example:
+
+```yaml
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+```
+
+### Body content
+
+The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
+
+Recommended sections:
+
+- Step-by-step instructions
+- Examples of inputs and outputs
+- Common edge cases
+
+Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.
+
+## Optional directories
+
+### scripts/
+
+Contains executable code that agents can run. Scripts should:
+
+- Be self-contained or clearly document dependencies
+- Include helpful error messages
+- Handle edge cases gracefully
+
+Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
+
+### references/
+
+Contains additional documentation that agents can read when needed:
+
+- `REFERENCE.md` - Detailed technical reference
+- `FORMS.md` - Form templates or structured data formats
+- Domain-specific files (`finance.md`, `legal.md`, etc.)
+
+Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
+
+### assets/
+
+Contains static resources:
+
+- Templates (document templates, configuration templates)
+- Images (diagrams, examples)
+- Data files (lookup tables, schemas)
+
+## Progressive disclosure
+
+Skills should be structured for efficient use of context:
+
+1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills
+2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
+3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
+
+Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
+
+## File references
+
+When referencing other files in your skill, use relative paths from the skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Validation
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
+
+```bash
+skills-ref validate ./my-skill
+```
+
+This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
@@ -0,0 +1,47 @@
+---
+name: formatting-commits
+description: Creates commits strictly following Conventional Commits format. Use when committing changes, amending commits, or when the user mentions git commits, conventional commits, or commit messages.
+compatibility: Requires `git` and `formatted-commit` CLI tools
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+Create/amend commits exclusively using `formatted-commit`. It has no sub-commands and the following options:
+
+<formatted-commit_flags>
+-t --type Commit type (required)
+-s --scope Commit scope (optional)
+-B --breaking Mark as breaking change (optional)
+-m --message Commit message (required)
+-b --body Commit body (optional)
+-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
+-a --add Stage all modified files before committing (optional)
+--amend Amend the previous commit (optional)
+-h --help
+</formatted-commit_flags>
+<formatted-commit_example>
+formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -b "$(cat <<'EOF'
+Multi-line
+
+- Body
+- Here
+
+EOF
+)"
+</formatted-commit_example>
+
+Most source code repositories require both an appropriate prefix _and_ scope. Necessity of scope increases with repository size; the smaller the repo, the less necessary the scope. Valid trailers for ticket tracking integration depend on the platform in use.
+
+- GitHub
+ - Closes:
+ - Fixes:
+ - Resolves:
+ - References:
+- SourceHut
+ - Closes:
+ - Fixes:
+ - Implements:
+ - References:
+
+Refer to [installing-formatted-commit.md](references/installing-formatted-commit.md) if it's unavailable.
@@ -0,0 +1,10 @@
+Ask the user which they prefer:
+
+- [bin](https://github.com/marcosnils/bin) (highly recommended because it's one tool to manage and update myriad CLI tools distributed as statically-linked binaries, like _formatted-commit_)
+ ```
+ bin install goinstall://git.secluded.site/formatted-commit@latest
+ ```
+- Using the [go toolchain](https://go.dev/dl) (upgrade with `formatted-commit upgrade`)
+ ```
+ go install git.secluded.site/formatted-commit@latest
+ ```
@@ -0,0 +1,20 @@
+---
+name: invoking-subagents
+description: Invokes ad-hoc subagents to read through lots of data and extract relevant information. Use only on explicit user request for exploring other repositories, reading series of git logs, looking at large diffs, and anything else that might produce copious amounts of text.
+compatibility: Requires `synu` shell plugin and `claude` CLI tool
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+Invoke with `synu claude --flags -p 'prompt'`.
+
+Use a precise and thorough prompt. Aggressively restrict which tools it can interact with; if it doesn't need Edit, don't give it Edit. If it needs to read files, Glob, Grep, and Read are probably sufficient. Task can be helpful. Notebook, Slash, Write, Web, Edit, etc. should almost never be necessary. Execute them in the background. You make invoke multiple when appropriate and in parallel if helpful. Once they're running, you may either stop and wait for me to tell you they're finished or continue with other work.
+
+A more thorough example using the fish plugin from another shell:
+
+```
+fish -c "synu claude --disallowed-tools 'Bash(*) Explore Edit Read WebFetch WebSearch Glob Grep NotebookEdit NotebookRead SlashCommand Write' --allowed-tools 'Bash(git log:*) Bash(git show:*)' -p 'Using only `git log` and `git show`, summarise the major user-facing changes in HASH..HASH. Do not provide code snippets or technical details. Consider user-facing changes, like being able to set a port-out PIN or adding a new button or changing font sizes.'"
+```
+
+Refer to [installing-synu.md](references/installing-synu.md) if it's unavailable.
@@ -0,0 +1 @@
+Depends on user's shell. Read https://git.secluded.site/synu/blob/main/README.md?raw=1 and ask them which shell/plugin manager they prefer. If their plugin manager isn't listed, it might not support arbitrary git hosts.
@@ -0,0 +1,12 @@
+---
+name: querying-documentation
+description: Invokes an agent to search specific sets of language/framework documentation and answer moderately complex queries. Use for exploring packages, asking about overall usage, and combining symbols across packages in a doc set.
+compatibility: Requires `fish` shell and `doc-agent` Fish function
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+`fish -c 'doc-agent'` spawns focused agents to trawl through docs for specific languages/tools. These agents have restricted tool access. List the available doc sets and see `doc-agent` usage by running `fish -c 'doc-agent -h'`. Your queries must include specific package or module references. Ask few questions, preferably one, per invocation. They must be precise, clear, high quality questions which elicit clear answers. A too-brief example query might be "Check path.to/module for how to use module.Type in module.Method".
+
+Refer to [installing-doc-agent.md](references/installing-doc-agent.md) if it's unavailable.
@@ -0,0 +1 @@
+Yoink it from https://git.secluded.site/yadr/blob/main/dot_config/private_fish/functions/doc-agent.fish?raw=1 into ~/.config/fish/functions/doc-agent.fish
@@ -0,0 +1,19 @@
+---
+name: resolving-secrets
+description: Wraps shell commands to resolve secret references in environment variables to their actual values. Always use when invoking synu, crush, gh, hut, etc. Ask whether to use if an invocation fails due to missing credentials.
+compatibility: Requires `fish` shell and `opx` Fish function
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+Prefix commands with `fish -c "opx ..."`.
+
+```bash
+fish -c "opx synu claude -p 'prompt'"
+fish -c "opx hut todo ticket show -t '~singpolyma/soprani.ca' 465"
+fish -c "opx gh issue view 123"
+fish -c "opx crush"
+```
+
+Refer to [installing-opx.md](references/installing-opx.md) if it's unavailable.
@@ -0,0 +1 @@
+Yoink it from https://git.secluded.site/yadr/blob/main/dot_config/private_fish/functions/opx.fish?raw=1 into ~/.config/fish/functions/opx.fish