agentleFS
narrative-ionarrative-io/narrative-skills-marketplace/AGENTS.md

narrative-skills-marketplace

AGENTS.md9 starsChanged 52 days agoMITView on GitHub

An agent skills marketplace. Plugins live under plugins/; each plugin contains one or more skills under plugins/<plugin>/skills/. Skills follow the Agent Skills spec; the bash setup installer currently targets Claude Code. Authoring a skill? docs/authoring-skills.md is the canonical guide — frontmatter contract, description writing, phased body structure, progressive disclosure, composition, the template / snippet system, and CI checks. The notes below are the 60-second tour. Two scheduled Claude jobs maintain this repo (both on Opus 5.5 via anthropics/claude-code-action): - audit-weekly.yml…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never use adjective-noun (/new-lead) or noun-noun (/campaign-brief).

    line 89
  2. Distinctive:

    Every skill file starts with YAML frontmatter:

    line 93
  3. Very specific:

    Create snippets/<name>.md (repo-shared) or plugins/<plugin>/_snippets/<name>.md (plugin-local.

    line 178
  4. Very specific:

    Run bun run gen:skill-docs to regenerate the rendered SKILL.md.

    line 189
  5. Very specific:

    Write scripts/resolvers/<name>.ts exporting a ResolverFn.

    line 196
  6. Very specific:

    Use {{YOUR_NAME}} or {{YOUR_NAME:arg}} in any template.

    line 198

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

narrative-skills-marketplace

An agent skills marketplace. Plugins live under plugins/; each plugin contains one or more skills under plugins/<plugin>/skills/. Skills follow the Agent Skills spec; the bash setup installer currently targets Claude Code.

Authoring a skill? docs/authoring-skills.md is the canonical guide — frontmatter contract, description writing, phased body structure, progressive disclosure, composition, the template / snippet system, and CI checks. The notes below are the 60-second tour.

Commands

bash setup   # register the marketplace + install every plugin

Project structure

narrative-skills-marketplace/
├── .claude-plugin/
│   └── marketplace.json        # Marketplace catalog (this repo)
├── plugins/
│   └── <plugin>/
│       ├── .claude-plugin/
│       │   └── plugin.json     # Plugin manifest (name, version, mcpServers)
│       ├── _snippets/          # (optional) plugin-local snippets
│       └── skills/
│           └── <skill>/
│               ├── SKILL.md.tmpl   # Template (source of truth, optional)
│               └── SKILL.md        # Rendered file (auto-generated if .tmpl exists)
├── snippets/                   # Shared snippets reused across skills
├── scripts/
│   ├── gen-skill-docs.ts       # Renders SKILL.md from SKILL.md.tmpl
│   ├── discover-skills.ts
│   ├── frontmatter.ts
│   └── resolvers/              # {{PLACEHOLDER}} resolver registry
├── package.json                # bun run gen:skill-docs
├── setup
└── README.md

Repo automation

Two scheduled Claude jobs maintain this repo (both on Opus 5.5 via anthropics/claude-code-action):

  • audit-weekly.yml (Mon 12:00 UTC) runs /audit-repo: grades one rubric from .claude/audit-rubrics/ (skills → tooling → automation, by ISO week) and files 0–5 repo-audit issues. It never edits files. Close an issue as not planned to decline it for good.
  • issue-burndown.yml (daily 13:00 UTC) runs /burndown-issues: picks one open issue, fixes it, and opens a PR for human review. It never merges. The queue is built first by bun run screen:issues, which drops issues from outside the org (unless labelled auto-fix-ok) and screens the rest for prompt injection with TypeSafe's Jev model. Add auto-fix-skip to keep an issue away from it.

Setup: repo variables ANTHROPIC_FEDERATION_RULE_ID and AUTOMATION_APP_ID, secrets AUTOMATION_APP_PRIVATE_KEY and TYPESAFE_API_KEY. Each workflow's preflight step names anything missing.

Naming conventions

Skills follow the verb-noun pattern (/triage-lead, /create-deck). Single-word names are fine when the verb is unambiguous (/commit, /qualify). Skill directory names match the slash command (lowercase, hyphen-separated).

VerbWhen to use
writeLong-form prose (/write-blog, /write-story)
createStructured artifacts (/create-slide, /create-pr)
triageCategorize + prioritize inbound items
reviewEvaluate existing content
startBegin a workflow
capturePersist an external artifact
findSearch existing material
prepPrepare for a specific event
buildAssemble multi-artifact output
sweepScheduled hygiene pass
registerAttach an existing external object to the platform

Never use adjective-noun (/new-lead) or noun-noun (/campaign-brief).

SKILL.md format

Every skill file starts with YAML frontmatter:

---
name: my-skill
version: 1.0.0
description: |
  One- or two-sentence description.
  Include trigger phrases: "use when X", "use when Y".
allowed-tools:
  - Bash
  - Read
  - Write
  - AskUserQuestion
---
  • name matches the slash command (no leading /).
  • allowed-tools lists every non-MCP tool the skill calls. AskUserQuestion is required for interactive skills. MCP tools declared in plugin.json are globally available and do not need to be listed.
  • The body is a phased, interactive workflow. Number phases sequentially (Phase 1, Phase 2, …).

Skill design principles

  1. Interactive, not reference — walk the user through decisions; don't just display docs.
  2. AI does the grunt work — research, enrichment, drafting. Humans approve.
  3. One question at a time — never batch multiple AskUserQuestions.
  4. Evidence over assumptions — never skip to conclusions without data.
  5. Drafts, not actions — for external-facing output (email, Slack), always draft and require explicit approval before sending.
  6. Graceful degradation — if an MCP tool isn't available, continue without it and note manual follow-ups.
  7. DRY via templates — pull shared boilerplate (company-context pinning, harness fallbacks, voice guidelines) out into snippets/ and reference it from a SKILL.md.tmpl instead of duplicating prose across skills.

Template system

Skills can be authored as a SKILL.md.tmpl with {{PLACEHOLDER}} substitutions; bun run gen:skill-docs (also invoked by bash setup) renders them to SKILL.md in place. Plain SKILL.md files with no template are left untouched.

Placeholder syntax

{{RESOLVER}}                # no-arg resolver
{{RESOLVER:arg1}}           # one arg
{{RESOLVER:arg1:arg2}}      # colon-separated args

Resolver names are UPPERCASE_WITH_UNDERSCORES. Unknown resolvers fail the render. Snippets that themselves contain {{...}} are resolved transitively (up to 5 passes).

Placeholders only resolve through .tmpl rendering. bun run gen:skill-docs only discovers and renders *.tmpl files. A {{SNIPPET:...}} (or any {{...}}) sitting in a plain .md that the renderer never processes is shipped verbatim — it will not resolve. So a placeholder is only effective when it lives in a .tmpl file or inside a snippet that gets inlined into one.

Snippet source files are the one deliberate exception, and they must stay .md: the resolver looks them up as <name>.md, so renaming a snippet to .tmpl makes it un-findable. A snippet may nest {{SNIPPET:...}} — those resolve only because the snippet is inlined into a .tmpl SKILL/reference, where the renderer's transitive passes pick them up. Never put a {{...}} placeholder in a hand-maintained .md reference (e.g. references/FOO.md); make it references/FOO.md.tmpl instead.

Built-in resolvers

PlaceholderWhat it does
{{SNIPPET:<name>}}Inlines snippets/<name>.md (or plugins/<plugin>/_snippets/<name>.md if the snippet is plugin-local).

Adding a snippet

  1. Create snippets/<name>.md (repo-shared) or plugins/<plugin>/_snippets/<name>.md (plugin-local; takes precedence). Write the markdown chunk verbatim, no frontmatter.
  2. Reference it from a template:

    ### Phase 2. Pin the company / context
    
    {{SNIPPET:pin-company-context}}
  3. Run bun run gen:skill-docs to regenerate the rendered SKILL.md.

Adding a resolver

For dynamic content (computed bash blocks, programmatic lookups, etc.) that can't be expressed as a static snippet:

  1. Write scripts/resolvers/<name>.ts exporting a ResolverFn.
  2. Register it in scripts/resolvers/index.ts.
  3. Use {{YOUR_NAME}} or {{YOUR_NAME:arg}} in any template.

The resolver signature is (ctx: TemplateContext, args?: string[]) => string. ctx provides the skill name, template path, and repo root.

Generated files

Rendered SKILL.md files start with an <!-- AUTO-GENERATED ... --> banner immediately after the frontmatter. Edit the .tmpl, never the rendered output. bun run check:skill-docs is a --dry-run check suitable for CI.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.