agentskill-config — Universal Config Base for Agent Skills

English | 繁體中文 | 简体中文 | 日本語 | Español | 한국어 | Português

✨ What it does

• Once installed, consumer skills only need a simple declaration in their SKILL.md to gain config support
• Global and project-scoped design, flexible to fit any skill's needs
• Automatically uses the skill name as the config key to avoid conflicts; also supports a shared _shared key mechanism
• Built on the standard Agent Skills spec, compatible with all major AI frameworks

🚀 How to Use

This skill is not triggered directly. It is loaded by other skills that declare a config section when they run.

Add the following block to the target skill's SKILL.md (recommended before the execution workflow):

## Skill Config

**MUST** use the `agentskill-config` skill's CLI, then read the table below to handle preference parameters.

| Key | Meaning | Scope |
|---|---|---|
| `your_key` | ... | global |

Just a few lines to give any skill unified preference config read/write capability.

🏗️ Architecture

agentskill-config/
├── SKILL.md
├── README.md
├── references/
│   └── api.md               ← CLI interface reference
└── scripts/
    └── agentskill-config.js ← Node.js implementation

Storage

Two-layer JSON files with per-key override priority: project overrides global; within the same layer, <skill-name> overrides _shared.

Scope	Path
global	$HOME/.agents/skill_config.json
project	<project-root>/.agents/skill_config.json

• <project-root> is resolved via git rev-parse --show-toplevel; falls back to cwd in non-git environments (warning printed to stderr)
• The project layer must be gitignored (personal preferences, not for team version control)

Schema

{
  "<skill-name>": { "<key>": <value> },
  "_shared": { "<key>": <value> }
}

• Top-level key: the skill's frontmatter name (kebab-case), or the reserved _shared
• Inner key: lower_snake_case
• Non-existent file is treated as {}

_shared Namespace

_shared is a reserved top-level key used when multiple skills share the same conceptual preference (e.g. multiple skills managing the same skills repo all need repo_path).

The key format in the consumer table determines the namespace:

Table entry	Meaning	Write target
<key>	Private to the skill	<skill-name>.<key>
_shared.<key>	Shared across skills	_shared.<key>

Read

Per-key fallback chain (<skill-name> overrides _shared; project overrides global):

1. project.<skill-name>.<key>
2. project._shared.<key>
3. global.<skill-name>.<key>
4. global._shared.<key>

The first non-null value is used; returns an empty string if none found.

Write

• Writes to the corresponding file by scope; parent directories are created automatically; idempotent merge preserves other keys in the file
• When writing to _shared, the CLI prints all skills referencing that key to stderr (impact scope); the agent should confirm with the user before proceeding

Restrictions

• No JSON read/write code, CLI commands, storage paths, or platform branching logic in SKILL.md
• No custom scope names (only global / project are allowed)
• No custom section names (only ## Skill Config is allowed)

🌐 Cross-Platform & Dependencies

• node (already required by the vercel-labs/skills CLI — no new dependencies)
• Cross-platform: a single Node.js implementation covers macOS / Linux / Windows (including native PowerShell, Git Bash, and WSL)