AI Skills

Shared, reusable skill repository for AI agents

Self-contained instruction sets that Claude Code, Cursor, and Cowork agents can install and use. The repository is actively growing — anyone can contribute.

What is an Agent Skill?

A skill is a self-contained folder of instructions that an AI agent loads on demand. Think of it as a plugin — but made of markdown, not code.

Skills are triggered by natural language. Say "fetch this page" or "check my timesheet" and the agent matches your intent to the right skill automatically.

my-skill/
├── SKILL.md  ← agent instructions
├── niss.json  ← metadata & versioning
├── scripts/  ← optional executables
├── references/  ← docs loaded on demand
└── assets/  ← templates, icons
Part 1

For Users

Install the skill manager, discover skills, and keep them up to date.

User

One-Line Install

The skill manager bootstraps itself — no repo clone needed. It's dog-fooded: the installer installs the skill manager, which is itself a skill that self-updates via its own sync mechanism.

macOS / Linux curl -fsSL https://niss.pages.dev/install.sh | bash
Windows irm https://niss.pages.dev/install.ps1 | iex

Auto-detects your agent: Claude Code (~/.claude/skills/) or Cursor (~/.cursor/skills/).
Override with --skill-root <path> or -SkillRoot <path>.

User

What the Skill Manager Does

Once installed, just talk to your agent in natural language:

Search

"Find skills for web scraping"

Install

"Install the sitemap skill"

Sync / Update

"Sync all my skills" — pulls latest versions, auto-backup

Upload

"Upload my skill to the repo" — creates a feature branch + PR

All operations preserve your .user/ data (credentials, preferences, caches) across updates.

Part 2

For Builders

Skill anatomy, contribution workflow, and advanced practices.

Builder

Skill Anatomy

Two Metadata Systems

niss.json

  • Read by the skill manager
  • Version tracking, discovery, install/sync
  • name, version, repoPath, description, triggers, author, updatedAt

SKILL.md frontmatter

  • Read by the agent runtime (Claude, Cursor)
  • Determines if the skill triggers for a user request
  • name + "pushy" description with synonyms

Progressive Disclosure

Skills load in three layers to keep agent context lean:

  • Layer 1 — Metadata
    Always in context (~100 words). Triggers loading.
  • Layer 2 — SKILL.md body
    Loaded when triggered. Keep under 500 lines.
  • Layer 3 — Resources
    scripts/, references/, assets/ — loaded on demand. Unlimited size.
Builder

How to Contribute

  1. Copy the template
    templates/skill-template/ → skills/<name>/
  2. Fill in niss.json
    Replace all placeholders. Name = kebab-case = folder name.
  3. Write SKILL.md
    Imperative LLM instructions, not human docs.
  4. Validate
    Name consistency, version bump, repoPath, triggers.
  5. Upload via the skill manager
    "Upload my skill" — quality review, feature branch, PR.

Validation Checklist

  • niss.json name = SKILL.md name = folder name
  • repoPath starts with skills/
  • Version bumped when behavior changes
  • updatedAt reflects today's date
  • Triggers are natural language, not function names
  • Description is "pushy" with synonyms & scenarios
Builder

SKILL.md Writing Principles

Do

  • Write for an LLM, not a human reader
  • Use imperative: "Read the file" not "The file should be read"
  • Explain why — the model generalizes better than ALWAYS/NEVER
  • Include concrete examples and expected output formats
  • Define error paths: "If the file doesn't exist, tell the user and ask..."
  • One operation = one capability, with a distinct trigger

Don't

  • "Handle errors appropriately" — too vague
  • Write documentation-style prose
  • Exceed 500 lines — overflow to references/
  • Use weak descriptions that won't trigger the skill
  • Forget to bump version on behavior changes
  • Use function names as triggers — use natural language
Builder — Advanced

Architecture: Three Locations & Two Dot-Dirs

Three-Location Model

  • Repo — source of truth on Azure DevOps. All authoring & PRs happen here.
  • SKILL_ROOT — agent's local skill directory (~/.claude/skills/, ~/.cursor/skills/). Installed copies live here.
  • <workspace> — user's project. Generated output goes to .session/.

Never edit .niss-repo-cache/ directly — it's a read-only mirror. Scripts use -w <workspace> for output placement.

Two Dot-Directories

  • .user/ — lives in the skill folder. Persistent user data: credentials, preferences, caches. Survives skill updates.
  • .session/ — lives in the workspace. Ephemeral generated output: fetched pages, reports, extracted docs.

Both are gitignored. .user/ is preserved during sync; .session/ is disposable.

Preflight & Dependencies

  • Add a preflight check for external tools (Node, Python, Playwright)
  • Use niss.json dependencies array for skill-to-skill deps
  • Cache results in .user/ to skip repeated checks
Builder — Advanced

Authentication & Credential Security

LLM Isolation — Core Principle

  • Scripts read credentials from files directly
  • The agent never sees secret values
  • Pass file paths as args, never credential values
  • Script output must not contain tokens or cookies

Agent conversation history may be logged or cached — credentials in context are credentials leaked.

Interactive Login Pattern

  • Agents can't handle stdin/TTY — no password prompts, no MFA
  • Guide the user to run login in their own terminal
  • Re-run preflight check to verify before continuing

Credential Storage

<skill-dir>/.user/
├── cookie.txt  ← session cookies
├── token.json  ← OAuth/JWT tokens
├── api-key.txt  ← API keys
└── prefs.json  ← non-secret prefs

Directory: chmod 700. Files: chmod 600. Set immediately after writing.

Token Lifecycle

  • Session cookies — user re-login (interactive)
  • OAuth tokens — script-level refresh, no user interaction
  • API keys — long-lived, guide user to regenerate if revoked
  • Use distinct exit codes: exit 2 for auth vs exit 1 for other errors
Builder — Advanced

Parallel Execution & Long-Running Tasks

Two Levels of Parallelism

  • Script-level — concurrency within one process (--concurrency 3). Best for batch ops against a single resource.
  • Agent-level — sub-agents via the Agent tool, each with its own context. Best for independent tasks across domains.

Max 5 concurrent sub-agents. One level deep — sub-agents don't spawn sub-agents.

Checkpoint & Resume

  • Cache-hit pattern: check if output exists before processing. Re-run resumes automatically.
  • Write progress.json with status, progress count, errors
  • Background tasks: use run_in_background: true for 2+ min tasks

Decision Matrix

Same domain batch I/O Script concurrency
Multi-domain batch Sub-agents, one per domain
Many identical files Sub-agents, 2–3 per batch
< 10 items Don't parallelize

Timeout & Retry

  • Per-item timeouts — don't let one stuck item block the batch
  • Exponential backoff: 1s → 2s → 4s, max 3 retries
  • 429/503 → retry. 404 → skip. 401/403 → stop, re-auth.
  • Collect failures, report once at the end

Start Building

Resources

  • agent.md — repo guide
  • skill-writing-guide.md
  • authentication-security.md
  • parallel-execution.md
  • templates/skill-template/
# Install the skill manager
bash install.sh

# Then ask your agent:
"search skills"
"install <skill-name>"
"sync all skills"
"upload my skill"
1 / 13